IamClient is the SDK’s single entry point. Construct one per IAM server you talk to and reuse it (it caches JWKS and, optionally, decisions).

import { IamClient } from '@padosoft/laravel-iam-node';

new IamClient(config)

Throws synchronously if baseUrl is missing, or if no fetch is available and none is injected.

const iam = new IamClient({
  baseUrl: 'https://iam.example.com/api/iam/v1',
  token: process.env.IAM_SERVICE_TOKEN,
});

Config (IamClientConfig)

JWKS are refetched at most every 10 minutes (plus a one-shot refetch on a key-rotation miss). This is not configurable.

check(query): Promise<Decision>

POST {baseUrl}/{checkPath}. Returns a normalised Decision. Never throws — every error path resolves to a deny.

const decision = await iam.check({
  subject: { type: 'user', id: 'usr_123' },
  application: 'warehouse',
  permission: 'stock.adjust',
  resource: { type: 'warehouse', id: 'wh_milan' },
  context: { amount: 300 },
  currentAal: 'aal1',
  explain: false,
});

Behaviour:

• A query with no subject.id returns deny('no-subject') without any network call.
• Serialises to the canonical wire body (see Wire contract).
• With caching on and explain !== true, returns a fresh cache hit; otherwise calls the PDP and caches the verdict.
• Any transport error / non-2xx / unparseable body returns deny('transport') — not cached.
• Unwraps a single { data } envelope and normalises with safe defaults.

See Checking permissions.

can(query): Promise<boolean>

check() reduced to the fail-safe boolean — true only when allowed && !requiresStepUp. Never throws.

if (!(await iam.can(query))) return res.status(403).end();

Equivalent to isGranted(await iam.check(query)). This is the method to gate on. See Step-up & AAL.

listResources(subject, relation): Promise<Resource[]>

POST {baseUrl}/{listResourcesPath}. ReBAC reverse query — the resources on which subject has relation. Fail-closed: returns [] on any error.

const warehouses = await iam.listResources({ id: 'usr_123' }, 'manage');
// → [{ type: 'warehouse', id: 'wh_milan' }, …]

Returns only entries shaped { type: string, id: string }; everything else is filtered out. An empty array can mean “no relationships” or an error — never treat it as a positive assertion. See ReBAC list-resources.

verifyToken(jwt, options?): Promise<Claims>

Verifies a JWT’s ES256 signature and iss / aud / exp / nbf against the server JWKS. Resolves to the verified Claims, or rejects with TokenVerificationError. A rejection is the fail-closed signal — treat it as deny.

const claims = await iam.verifyToken(bearer, { audience: 'warehouse' });

Options (VerifyOptions)

Options merge over the client’s verify defaults. Rejects when: the token is empty; no audience is resolvable; the signature/claims fail; the JWKS is unreachable or malformed. On a no-matching-key error it refetches the JWKS once (rotation) and retries before rejecting. See Token verification theory.

Exported helpers

index.ts also exports the pure decision helpers, useful when you hold a Decision directly:

Next steps

• Middleware API — requirePermission.
• Types — every interface.
• Errors — TokenVerificationError.