{"_id":"@aauth/protocol","_rev":"3-b87e1eff720c4b85e199cbfede6d538f","name":"@aauth/protocol","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"@aauth/protocol","version":"1.0.0","keywords":["aauth","agent-auth","http-headers","access-mode"],"author":{"name":"Dick Hardt","email":"dick.hardt@hello.coop"},"license":"MIT","_id":"@aauth/protocol@1.0.0","maintainers":[{"name":"dickhardt","email":"dickhardt@gmail.com"},{"name":"rohanharikr","email":"rohanharikumar80@gmail.com"}],"homepage":"https://github.com/aauth-dev/packages-js#readme","bugs":{"url":"https://github.com/aauth-dev/packages-js/issues"},"dist":{"shasum":"f1a1b036e775febbee515074bd0f12064e4fa75b","tarball":"https://registry.npmjs.org/@aauth/protocol/-/protocol-1.0.0.tgz","fileCount":26,"integrity":"sha512-xnmiXGpBecF2lmZukbClhrODA/L0x6CalS8OrjTvWktCFPicVK7f+fJB2cdH8lGJ6Bk0Tls5vVpeXK56ew7rtA==","signatures":[{"sig":"MEYCIQDsxNiAqJ5NgKGHeoy/m/kauMwPIjKOLJfmUkNsGNkgnQIhAMq+eZlC8R5QDdntekMq6qehTlAOSMU3WVJnmhT0sfVB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38949},"type":"module","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"dickhardt","email":"dickhardt@gmail.com"},"repository":{"url":"git+https://github.com/aauth-dev/packages-js.git","type":"git","directory":"protocol"},"_npmVersion":"11.16.0","description":"AAuth wire format — AAuth-Requirement and AAuth-Capabilities headers, access_mode planning, protocol constants","directories":{},"_nodeVersion":"22.22.3","dependencies":{"@hellocoop/httpsig":"^2.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/protocol_1.0.0_1786634784488_0.8949671719459289","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aauth/protocol","version":"1.0.1","keywords":["aauth","agent-auth","http-headers","access-mode"],"author":{"name":"Dick Hardt","email":"dick.hardt@hello.coop"},"license":"MIT","_id":"@aauth/protocol@1.0.1","maintainers":[{"name":"dickhardt","email":"dickhardt@gmail.com"},{"name":"rohanharikr","email":"rohanharikumar80@gmail.com"}],"homepage":"https://github.com/aauth-dev/packages-js#readme","bugs":{"url":"https://github.com/aauth-dev/packages-js/issues"},"dist":{"shasum":"5b79187d35dc7ceb96ebfc16d009fe545c1ba05b","tarball":"https://registry.npmjs.org/@aauth/protocol/-/protocol-1.0.1.tgz","fileCount":26,"integrity":"sha512-JMyQVl+kpfDUE5t9PSzybDHu0yTmFpZk5ePyflnE1blpeAmmTXyL8AwRO+OiFAgdyUYvo/XCLrCEryoag3zGiw==","signatures":[{"sig":"MEUCIQC/IYXgFEfSWkYcPztfIXHEKgDt7niY8+uwKVjtWAH6KAIgAx3RSIwTuHvihZ6NouZlpE3tsfVixbwJM/Xk3QKJHts=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aauth%2fprotocol@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":38949},"type":"module","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"8998c7250424a6505b154f5ce22638df7db030e6","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:1d63bb7a-519f-4b4b-95e7-12c618cdb908"}},"repository":{"url":"git+https://github.com/aauth-dev/packages-js.git","type":"git","directory":"protocol"},"_npmVersion":"11.17.0","description":"AAuth wire format — AAuth-Requirement and AAuth-Capabilities headers, access_mode planning, protocol constants","directories":{},"_nodeVersion":"24.19.0","dependencies":{"@hellocoop/httpsig":"^2.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/protocol_1.0.1_1786706011758_0.6864043240323052","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@aauth/protocol","version":"2.0.0","description":"AAuth wire format — AAuth-Requirement and AAuth-Capabilities headers, access_mode planning, protocol constants","type":"module","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc","prepublishOnly":"npm run build"},"keywords":["aauth","agent-auth","http-headers","access-mode"],"author":{"name":"Dick Hardt","email":"dick.hardt@hello.coop"},"license":"MIT","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/aauth-dev/packages-js.git","directory":"protocol"},"dependencies":{"@hellocoop/httpsig":"^2.4.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0"},"gitHead":"381ad53efd36fe709ca36d496a62bba5dba1610f","_id":"@aauth/protocol@2.0.0","bugs":{"url":"https://github.com/aauth-dev/packages-js/issues"},"homepage":"https://github.com/aauth-dev/packages-js#readme","_nodeVersion":"22.22.3","_npmVersion":"11.16.0","dist":{"integrity":"sha512-xoAJfZnwgEZ21wFZYI6tNEvmKhTgKv4+ETkxP8knZsMaVOz42MXV9lvyPOGXCnZy+qu1Z3XQxXEsD82blPTqrg==","shasum":"3bf98b83dde26f1797e641eaa609cd34348d4b52","tarball":"https://registry.npmjs.org/@aauth/protocol/-/protocol-2.0.0.tgz","fileCount":26,"unpackedSize":39367,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIATHaq3W6Fc31LD6wbw6CcC0GWli6t2XMmswRj9bD5NcAiEA1S1Fgtkt2cYmYAvlTudQXSCs9d+0lYemaRzCKuljyJ8="}]},"_npmUser":{"name":"dickhardt","email":"dickhardt@gmail.com"},"directories":{},"maintainers":[{"name":"dickhardt","email":"dickhardt@gmail.com"},{"name":"rohanharikr","email":"rohanharikumar80@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/protocol_2.0.0_1788940551561_0.7478119021611946"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-13T15:26:24.273Z","modified":"2026-09-09T07:55:52.055Z","1.0.0":"2026-08-13T15:26:24.684Z","1.0.1":"2026-08-14T11:13:31.912Z","2.0.0":"2026-09-09T07:55:51.673Z"},"bugs":{"url":"https://github.com/aauth-dev/packages-js/issues"},"author":{"name":"Dick Hardt","email":"dick.hardt@hello.coop"},"license":"MIT","homepage":"https://github.com/aauth-dev/packages-js#readme","keywords":["aauth","agent-auth","http-headers","access-mode"],"repository":{"type":"git","url":"git+https://github.com/aauth-dev/packages-js.git","directory":"protocol"},"description":"AAuth wire format — AAuth-Requirement and AAuth-Capabilities headers, access_mode planning, protocol constants","maintainers":[{"name":"dickhardt","email":"dickhardt@gmail.com"},{"name":"rohanharikr","email":"rohanharikumar80@gmail.com"}],"readme":"# @aauth/protocol\n\nThe AAuth wire format, on its own. Header build/parse, `access_mode` planning,\nprotocol constants, and unverified JWT decoding. No I/O, no crypto.\n\nTracks `draft-hardt-oauth-aauth-protocol-11`.\n\nOne runtime dependency: [`@hellocoop/httpsig`](https://www.npmjs.com/package/@hellocoop/httpsig),\nimported for its RFC 8941 structured field parser\n(`@hellocoop/httpsig/structured-fields`). `AAuth-Requirement` is a Dictionary\nand `AAuth-Capabilities` is a List of Tokens, and every consumer of this\npackage signs its requests with `@hellocoop/httpsig` anyway — so the parser is\nalready installed, and a second implementation of the same grammar is a second\nplace for the quoting and escaping rules to be got wrong.\n\n```\nnpm install @aauth/protocol\n```\n\n## AAuth-Requirement\n\n```ts\nimport { parseRequirementHeader, buildRequirementHeader, UnsupportedRequirementError }\n  from '@aauth/protocol'\n\n// resource side\nres.setHeader('AAuth-Requirement', buildRequirementHeader({\n  requirement: 'auth-token',\n  resourceToken,\n}))\n\n// agent side\ntry {\n  const challenge = parseRequirementHeader(res.headers.get('AAuth-Requirement')!)\n} catch (e) {\n  if (e instanceof UnsupportedRequirementError) {\n    // MUST NOT treat the response as satisfiable. Surface e.value to the caller.\n  }\n}\n```\n\nRecognized values: `agent-token`, `person-token`, `auth-token`, `approval`,\n`interaction`, `clarification`, `claims`. Anything else throws\n`UnsupportedRequirementError`, carrying the raw `value`. For a `202` the caller\nMAY keep polling `Location` in case a later response carries a value it knows.\n\n`requirement=auth-token` requires a `resource-token` parameter and\n`requirement=interaction` requires `code`; a header missing one is malformed and\nthrows a plain `Error`. `url` on `requirement=interaction` is optional: when it\nis absent the recipient composes `{interaction_endpoint}?code=…` from the\nissuer's published metadata. Unknown parameters are ignored.\n\n## AAuth-Capabilities\n\n```ts\nbuildCapabilitiesHeader(['interaction', 'clarification'])  // \"interaction, clarification\"\nparseCapabilitiesHeader('interaction, quantum-consent')    // [\"interaction\"]\n```\n\nParsing filters unrecognized values and never throws — recipients MUST ignore\nwhat they do not recognize. Building does not filter: an agent unions its own\ncapabilities with the ones its PS reports, which may be newer than this library.\n\nAn absent header is not an empty one. When the header is absent, recipients MUST\nNOT assume any capabilities.\n\n## access_mode\n\n`access_mode` in `/.well-known/aauth-resource.json` is advisory — the runtime\n`AAuth-Requirement` is authoritative. `planAccessMode` gives an agent one of\nthree answers and never throws.\n\n```ts\nconst plan = planAccessMode(metadata.access_mode, { hasPersonServer: false })\n\nswitch (plan.kind) {\n  case 'undeclared':     // absent or unrecognized — call the resource anyway\n  case 'satisfiable':    // plan.mode is reachable with this setup\n  case 'unsatisfiable':  // skip the resource, show plan.reason\n}\n```\n\nUnrecognized values are `undeclared`, not errors: the value space is the AAuth\nAccess Mode Value Registry, and an agent that stops on an unknown value breaks\nevery time a value is registered.\n\n`unsatisfiable` comes from an agent token with no `ps` claim. Three of the five\nmodes reach a person server, and without one none of them can complete:\n\n| Mode | No person server | Why |\n| --- | --- | --- |\n| `agent-token` | satisfiable | Identity only; no PS in the flow. |\n| `session-token` | satisfiable | Resource-managed; the resource issues its own credential. |\n| `person-token` | **unsatisfiable** | The agent must sign with a person token, which only a PS issues. |\n| `auth-token` | **unsatisfiable** | The resource token is exchanged for an auth token at the PS. |\n| `per-call` | **unsatisfiable** | Terminates in an auth token — the grant is the `r3_per_call` claim. |\n\n## Constants\n\n`TOKEN_TYP` (the four `typ` values), `DWK` (the four well-known key documents),\n`SIGNING_ALG` — `Ed25519`, fully specified per RFC 9864. The polymorphic\n`EdDSA` MUST NOT be used.\n\n## JWT decoding\n\n`decodeJwtHeader` and `decodeJwtPayload` parse a token's segments and throw on\nanything malformed. **No signature verification.** They prove nothing; never\nmake a trust decision on their output.\n\n## Not here\n\n`AAuth-Mission` was removed in -11, along with its IANA registration. A mission\nreaches a resource only inside a PS-issued token, as the `mission_s256` claim.\nThere are no mission header helpers in this package and there will not be.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}