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.

Delegated access

Present only when the server runs laravel-iam-agents. Full walkthrough: Delegated access.

checkDelegated(subject, actors, permission, options?): Promise<Decision>

Asks whether an agent may act on behalf of a user. Routes to POST {baseUrl}/decisions/check-delegated, sending actors (and delegation_grant_id when supplied) alongside the normal body. The verdict is the strict intersection of the subject and every actor — never the union.

Denies without calling the server when: the subject has no id (no-subject), or the chain is empty after dropping blanks (no-actor). Everything else is fail-closed as usual.

canDelegated(subject, actors, permission, options?): Promise<boolean>

isGranted(await checkDelegated(...)) — true only when allowed and no step-up is pending.

verifyDelegatedToken(jwt): Promise<DelegatedBearer | null>

Verifies a delegated bearer through RFC 7662 introspection and returns the authorization view, or null. Fail-closed without throwing: every failure path resolves to null.

interface DelegatedBearer {
  sub: string;        // the delegating user
  actors: string[];   // act chain, current actor first
  grantId: string | null;
  scopes: string[];
  verified: boolean;  // always true on a value returned by this method
}

Returns null when: the token is not a JWT; it is not delegated (use verifyToken instead — this is not an error); the act is malformed; introspectionUrl is empty; introspection is unreachable or non-200; the response says active: false; the response omits sub or carries an unreadable act.

Delegated decisions bypass the cache unconditionally, so a revocation is never masked by a cached allow.

Delegation helpers

Lower-level exports, for callers doing their own routing:

Exported helpers

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

Next steps

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