@aauth/resource

@aauth/resource

The resource-side reference implementation of AAuth. Verify what an agent presents, mint what a resource issues, publish and enforce R3.

Formerly @aauth/mcp-server. It contains no MCP and never did — it is the library a resource uses, whatever protocol the resource speaks.

Runs on Cloudflare Workers. This package imports no node:* built-ins; it uses only crypto, crypto.subtle, fetch, TextEncoder and TextDecoder.

Header construction and parsing live in @aauth/protocol and are re-exported here, so a resource has one import.

Install

npm install @aauth/resource

Verifying what the agent presented

import { verifyToken, AAuthTokenError } from '@aauth/resource'

const verified = await verifyToken({
  jwt: sig.jwt.raw,                       // from @hellocoop/httpsig
  httpSignatureThumbprint: sig.thumbprint,
  resource: 'https://notes.example',      // this resource's own identifier
  accept: ['auth'],                       // what THIS endpoint requires
})

accept is required and there is no default. A person token and a PS-issued auth token carry the same iss, dwk, aud, sub and cnf; only typ distinguishes them. An endpoint that requires authorization passes ['auth']. Passing ['auth', 'person'] there accepts an identity assertion as a grant, and the mistake fails open — so the check is a parameter you must state, not one you can forget.

verifyToken performs: typ recognition → the accept check → required-claim structure → exp in the future and iat not in the future → key binding (cnf.jwk against the HTTP signing key) → kid selection and signature verification against the JWKS discovered at {iss}/.well-known/{dwk} → iss a valid HTTPS server identifier → aud equal to resource. Nothing is acted on before the signature verifies.

The polymorphic EdDSA identifier is rejected in both the JWT header and cnf.jwk, per RFC 9864.

Results

type	Shape
'agent'	iss, sub, jti?, ps?, parent_agent?, cnf, iat, exp, claims
'person'	iss, aud, sub, jti, mission_s256?, tenant?, cnf, iat, exp, claims
'auth'	iss, aud, ps, sub, scope?, account?, mission_s256?, tenant?, r3_uri?, r3_s256?, r3_granted?, r3_per_call?, cnf, iat, exp, claims

There is no agent claim in AAuth -11 and none is surfaced. A resource learns which agent it is talking to from the agent token, and binds authorization to the key via agent_jkt / cnf.

sub is unique within the issuer, not globally. Treat (iss, sub) as the identity, treat sub as opaque, and never match a sub from one issuer against a record established under another, however the values compare.

Errors

AAuthTokenError carries a stable code. Branch on code, never on message.

Code	Meaning
unsupported_token_type	typ is not an AAuth token type
token_type_not_accepted	Recognized, but not allowed at this call site — including a person token where an auth token is required
invalid_agent_token / invalid_person_token / invalid_auth_token	Structure, discovery or signature failed
token_expired	exp is in the past
aud_mismatch	aud is not this resource
key_binding_failed	cnf.jwk is not the key that signed the request
metadata_fetch_failed	{iss}/.well-known/{dwk} could not be read
invalid_configuration	accept or resource was not supplied correctly

Challenging

import { buildAAuthHeader } from '@aauth/resource'

buildAAuthHeader('agent-token')    // 401 — present your agent token
buildAAuthHeader('person-token')   // 401 — obtain a person token from your PS and retry
buildAAuthHeader('auth-token', { resourceToken })
buildAAuthHeader('interaction', { url, code })   // 202
buildAAuthHeader('approval')
buildAAuthHeader('clarification')
buildAAuthHeader('claims')

A resource MUST have verified a person token before it issues a resource token, and MUST challenge with requirement=person-token when it has not.

buildMissionHeader, parseMissionHeader and the AAuthMission type are gone. The AAuth-Mission header and its IANA registration were removed in -11. A mission reaches a resource only inside a PS-issued token, as mission_s256.

Minting a resource token

import { createResourceToken } from '@aauth/resource'

const resourceToken = await createResourceToken(
  {
    resource: 'https://notes.example',   // iss
    audience: psUrl,                     // aud: the PS (three-party) or the AS (four-party)
    personToken: verifiedPersonToken,    // ps, sub, person_token_jti, mission_s256, tenant come from here
    agentJkt: sig.thumbprint,
    scope: 'notes.read notes.write',
    kid: publicJwk.kid,
    r3: { uri: r3_uri, s256: r3_s256 },  // optional; both or neither
    missionExpiresAt,                    // optional clamp
  },
  async (payload, header) => signJwt(header, payload, privateKey),
)

The header handed to your signer is { alg: 'Ed25519', typ: 'aa-resource+jwt', kid? }. Sign it as given — alg is the fully-specified RFC 9864 identifier, and the polymorphic EdDSA MUST NOT be used.

mission_s256 is copied from the person token unchanged and is REQUIRED when the person token carried one; a resource MUST NOT omit it. The PS resolves the person token by person_token_jti and compares, so dropping it is detected as mission stripping.

clampToMission(exp, missionExpiresAt) is exported for anything else a resource derives from a mission-scoped token: no token carrying mission_s256 may outlive its mission.

R3 documents

import { publishR3Document, serveR3Document } from '@aauth/resource'

const { r3_uri, r3_s256 } = await publishR3Document({
  document: {
    vocabulary: 'urn:aauth:vocabulary:mcp',
    operations: [{ tool: 'create_note' }],
    display: { summary: 'Create notes in your notebook' },
  },
  baseUri: 'https://notes.example/r3',
  store,
  authorized: [psUrl, agentToken.ps],   // see below
})

Serialize once, serve those exact bytes. r3_s256 is the SHA-256 of the bytes as served, with no canonicalization step. Any re-stringify — middleware that parses and re-encodes JSON, a framework json() helper, CDN minification, key reordering — changes the bytes and breaks hash verification at the PS and AS. publishR3Document serializes once and stores the result; serveR3Document returns those bytes verbatim. Write the returned body to the wire as-is; do not pass it through a JSON response helper.

R3 -02 removed the version field. Including one is rejected.

The store you supply

interface R3Store {
  get(key: string): Promise<R3Record | null>
  put(key: string, record: R3Record, ttlSeconds?: number): Promise<void>
}

interface R3Record {
  uri: string          // the r3_uri this is served at
  s256: string         // BASE64URL(SHA-256(body)) — the r3_s256 claim
  body: string         // the exact bytes to serve
  authorized: string[] // server identifiers entitled to fetch it
  createdAt: number
  expiresAt?: number
}

Two methods, both keyed by opaque string. Back it with Workers KV (put(key, JSON.stringify(record), { expirationTtl }) / get(key, 'json')), Redis, or anything else — body is a string and survives a JSON round trip unchanged. MemoryR3Store is a conforming in-memory implementation for tests and single-process deployments.

Each record is written under two keys: its s256 and its uri. The fetch path knows only the URI; the per-call retry path knows only the hash from the auth token. Both resolve.

Access restriction

Agents must never read an R3 document — agent opacity depends entirely on it. Exactly two parties are entitled:

• the AS named in the aud of a resource token carrying that r3_uri; and
• the PS named by the ps claim of the agent token the agent presented.

Pass both to publishR3Document as authorized. In three-party access they are the same party.

const res = await serveR3Document({ store, key: url.pathname.split('/').pop()!, signer })
// 401 unsigned · 403 wrong signer · 404 unknown · 200 with the exact stored bytes

signer is the server identifier established from the verified HTTP Message Signature on the fetch — not a header the caller controls. Comparison is exact string equality.

Per-call proposals

An r3_per_call operation is authorized in principle but not for any specific call. When the agent invokes one, build a proposal: a full R3 document scoped to that one invocation, carrying a REQUIRED parameters object.

import { publishProposal, digestParameter, verifyProposalParameters } from '@aauth/resource'

// 1. Challenge
const proposal = await publishProposal({
  vocabulary: 'urn:aauth:vocabulary:mcp',
  operation: { tool: 'send_email' },
  parameters: {
    to: '[e-mail]',
    subject: 'Dinner Sunday?',
    body: await digestParameter(emailBody, { media_type: 'text/plain' }),
  },
  display: { summary: 'Send an email as you', detail: '## Action\nSend an email\n\n## To\[e-mail]' },
  store,
  baseUri: 'https://mail.example/r3',
  authorized: [asUrl, agentToken.ps],
})
// mint a resource token with r3: { uri: proposal.r3_uri, s256: proposal.r3_s256 }

// 2. …the AS evaluates the parameters, the PS renders `display`, the agent retries…

// 3. Enforced retry
await verifyProposalParameters({
  store,
  r3_s256: authToken.r3_s256!,
  presented: call.arguments,
  operation: { tool: 'send_email' },
})

verifyProposalParameters rejects on any difference: a parameter the proposal did not carry, an approved parameter missing from the call, a structural value that does not deep-equal the approved one, or a digest parameter whose bytes do not satisfy BASE64URL(SHA-256(presented)) === s256. An approval to email one recipient cannot be replayed against another.

digestParameter keeps a large or sensitive value out of every token and away from the PS: only the hash and a short excerpt appear in the proposal. The full bytes travel agent → resource at call time, where they are verified against the digest.

The token carries only r3_uri / r3_s256, never the parameters.

Interaction (202 deferred responses)

import { InteractionManager } from '@aauth/resource'

const manager = new InteractionManager({
  baseUrl: 'https://notes.example',
  interactionUrl: 'https://notes.example/interact',
})

const { headers, pending } = manager.createPending()
// headers: Location, Retry-After, Cache-Control, AAuth-Requirement
manager.resolve(pending.id, { granted: true })

This is the only part of the package with a transitive node:crypto dependency, via @aauth/interaction-code. On Workers it needs nodejs_compat, which workerd supports.

License

MIT