Decision client and framework adapters

createIdentity is imported from the SDK's root entry.

import { createIdentity } from '@tdacorp/identity-sdk'const identity = createIdentity({  issuer: 'https://identity.tdacorp.in',  clientId,  ns: 'eidos',  audience: 'https://api.example.com',})

Methods#

The data methods below write to or search your product's resource graph. They throw IdentityRequestError on a failed call and NotAvailableError when identity answers 404, which is what a flag that is off looks like, so a product can degrade. Each request body is checked locally and an unknown field is refused.

A write or search request carries at most 500 items; the client splits a larger list into several requests, one after another. They are not atomic across requests: if a later one fails, the earlier ones stay applied and the error says so.

token is a string, which the client verifies first, or an already verified token.

Results#

A CheckResult has decision (ALLOW, DENY or INDETERMINATE), reasonCode, vector (av, pv, pvt, and rv when identity sends it), evaluatedAt, ttlHint, hints and source.

source says where the answer came from: pdp (identity), cache, last_known_good, or sdk (the client refused without asking). An SDK-made refusal uses one of these reason codes.

Only ALLOW permits. The client never produces an ALLOW that identity did not send.

Caching#

Identity decides how long an answer may be reused (ttlHint). The default in-memory cache stores only ALLOW answers from identity, for ttlHint seconds, and never when the hint is 0. When identity sets hints.last_known_good, a prior ALLOW for the same question, at most 300 seconds old and with unchanged av, pv and pvt, may be used instead of a failure. The cache is per process and holds 10,000 entries by default.

Read-your-writes is automatic. The client remembers the highest rv (the organization's resource version) it has seen, from a write result or a token, and sends it as min_rv with the next check. If identity has not caught up it answers indeterminate_consistency; the client retries once after a short pause and otherwise returns that INDETERMINATE, never an ALLOW. An answer about a resource is cached under the rv it was decided at, so a write moves it to a new key.

With events: true the cache also follows identity's invalidation stream: a change to a person's authority drops that person's cached answers at once, and a cached answer is served only while the stream vouches for the organization's policy version. After a disconnect longer than 30 seconds, answers with a ttlHint of 60 or less are no longer served. A stream that cannot connect makes the cache miss; it never fails a call.

A token that carries an act claim (a delegated agent) is sent to identity whole as the subject_token, so the decision follows its delegation chain and agent_action, and its answers are cached per token. Identity reads the token only while the pdp_subject_token flag is on, and it defaults OFF. When identity refuses that form, the client falls back to the plain request, which carries no delegation: an agent token is then INDETERMINATE, but an impersonation token decides with the person's full authority, so set refuseActorTokens unless you intend that.

Each adapter does the same work in front of a route: verify the token, check proof of possession for a bound token, resolve the resource, ask check, and refuse or let the request through. Each is its own subpath.

import { pepRoute } from '@tdacorp/identity-sdk/next'export const GET = pepRoute({  identity,  action: 'eidos.document.read',  resource: (request, context) => 'eidos:document:q3-plan',  proofOfPossession,})(async (request, context, allowed) => Response.json({ caller: allowed.subject.subject }))

Options#

Refusals#

A refusal is application/problem+json with title, status, detail and reason_code. It is 401 when the token failed verification or proof, with a WWW-Authenticate header that offers Bearer and DPoP. An adapter option requireAuthentication ({ acrValues?, maxAgeS? }, RFC 9470) also answers 401 when the token verified but its acr is too weak or its auth_time too old: the challenge is insufficient_user_authentication with the required acr_values and max_age, and the client steps up with rp.stepUpUrl (Relying-party module). It is 403 for every other refusal. A failure to decide is a refusal, never an allow.

Identity authenticates the caller of the decision API, not the person: your product's service client, with its own DPoP-bound access token and a fresh DPoP proof for every request. The headers option is a function that receives { method, url, nonce? } for each attempt and returns the request headers, so it can sign a proof for exactly that request. pdpCredential builds it from a service client.

import { createIdentity } from '@tdacorp/identity-sdk'import { createServiceClient, pdpCredential } from '@tdacorp/identity-sdk/service'const service = createServiceClient({  issuer,  clientId,  key: { kid: 'k1', privateKey: privateJwk },  dpop,})const identity = createIdentity({  issuer,  clientId,  ns: 'eidos',  headers: pdpCredential(service),})

pdpCredential uses the service client's own token (audience is the client itself), never an exchanged one. The service client must hold a DPoP key, because identity refuses an unbound token on this API. The returned headers are secrets: do not log them.

• Fail closed. INDETERMINATE and every indeterminate_sdk_* code mean refuse.
• Enforce where the resource is. The adapter is your product's enforcement point; identity is the decision point.
• Do not cache your own answers. Use the client's cache, which honours ttlHint and the version vector.

• Authorization decision API
• Authorization
• Protect your API