@owlmeans/auth-token 0.1.18-rc.8 → 0.1.18

package/README.md

@@ -1,3 +1,166 @@
+# @owlmeans/auth-token
+
+The contract half of long-lived access tokens (API keys) on the OwlMeans auth rails: the stored
+record shape, the token format and its deployment prefix, the three management route declarations
+with their AJV schemas, `Authorization` header parsing that accepts `Bearer`, and a client-side
+carrier guard that presents a token it was handed. A shared package imports it to declare the token
+routes and types; a CLI, a test or an MCP connector imports it for the carrier guard. It stores and
+verifies nothing — the token store, the verifying guard and the handlers are
+`@owlmeans/server-auth-token`, and the management UI is `@owlmeans/web-auth-token`. Browser sessions
+are `@owlmeans/client-auth`, not this package.
+
+## Installation
+
+```bash
+bun add @owlmeans/auth-token@^0.1.18
+```
+
+## Concepts
+
+- **Token** — `<prefix><base58 of 24 random bytes>`. The prefix (`owl_` by default, overridden per
+  deployment) makes a token claimable: a guard matches only values that start with it, so an access
+  token and a session bearer share the `Authorization` header without shadowing each other.
+- **Record** — `AccessTokenRecord`: the SHA-256 `hash` of the plaintext (never the plaintext), a
+  `display` form, the owning `userId`/`profileId`/`entityId`, `scopes`, `role`, timestamps and an
+  optional OAuth `audience`.
+- **Display** — the prefix plus `AUTH_TOKEN_DISPLAY_LENGTH` (8) characters of the secret; enough to
+  tell tokens apart, useless as a credential. The plaintext appears once, in `IssuedAccessToken`.
+- **Management surface** — `list`, `create` and `revoke` only. There is no update: scopes and
+  lifetime are fixed at issuance.
+- **Audience** — `audience?: string[]` is set only on tokens minted through an OAuth grant; a guard
+  configured with `resources` admits such a token only when the lists intersect.
+- **Carrier guard** — a client `GuardService` with no session, refresh or storage; `authMiddleware`
+  stamps its `authenticated()` answer onto the request header.
+
+## Usage
+
+### Declare the management routes
+
+Mount the base under an account section so the ownership gate already guarding a person's settings
+guards their tokens too.
+
+```typescript
+import { makeAuthTokenEntrypoints } from '@owlmeans/auth-token'
+
+export const tokenEntrypoints = makeAuthTokenEntrypoints({ parent: account.base, path: '/tokens' })
+
+context.registerEntrypoints(tokenEntrypoints)
+```
+
+A base without a parent carries `opts.guard` instead:
+
+```typescript
+import { GUARD_AUTH_TOKEN, makeAuthTokenEntrypoints } from '@owlmeans/auth-token'
+
+const tokens = makeAuthTokenEntrypoints({ guard: GUARD_AUTH_TOKEN })
+```
+
+### Authenticate a non-browser client with a token
+
+Register the carrier under the alias the routes already name, and unchanged route declarations work
+from a CLI or a connector.
+
+```typescript
+import { DEFAULT_GUARD, authMiddleware } from '@owlmeans/auth-common'
+import { makeTokenCarrierGuard } from '@owlmeans/auth-token'
+
+context.registerService(makeTokenCarrierGuard(DEFAULT_GUARD, {
+  token: () => process.env.OWL_TOKEN ?? '',   // a thunk is re-read on every request
+  scheme: 'bearer',                            // default 'auth-token' → `AUTH-TOKEN <token>`
+  onRejected: async () => { await signInAgain() },
+}))
+context.registerMiddleware(authMiddleware)
+```
+
+### Parse and display tokens
+
+```typescript
+import { AUTH_TOKEN_DEFAULT_PREFIX, BEARER_SCHEME, AUTH_TOKEN_SCHEME, tokenFormatHelper } from '@owlmeans/auth-token'
+
+const header = tokenFormatHelper.parseAuthorizationHeader(req.headers.authorization)
+if (header != null && (header.scheme === BEARER_SCHEME || header.scheme === AUTH_TOKEN_SCHEME)
+  && tokenFormatHelper.isAccessToken(header.value, AUTH_TOKEN_DEFAULT_PREFIX)) {
+  // claim it
+}
+
+tokenFormatHelper.displayOf('owl_ABCDEFGHIJKLMNOP', 'owl_')   // 'owl_ABCDEFGH'
+```
+
+### Create a token from a client
+
+```typescript
+import type { CreateAccessToken, IssuedAccessToken } from '@owlmeans/auth-token'
+
+const body: CreateAccessToken = { name: 'CI deploy', scopes: ['project:read'], expiresIn: 30 * 24 * 3600 }
+const issued: IssuedAccessToken = await context.entrypoint(tokenEntrypoints.create).call({ body })
+// issued.token is the only time the plaintext is available
+```
+
+## API
+
+### Functions and helpers
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeAuthTokenEntrypoints(opts?)` | function | `{ base, list, create, revoke }` protocols: `GET /`, `POST /`, `DELETE /:id` under `opts.path ?? '/tokens'`; `opts.parent` or `opts.guard` for the base |
+| `makeTokenCarrierGuard(alias, opts)` | function | client `GuardService`; `authenticated()` → `AUTH-TOKEN <t>` or `Bearer <t>`, `null` for an empty token; `update()` calls `opts.onRejected` |
+| `tokenFormatHelper`, `createTokenFormatHelper()` | helper | the three members below |
+| `tokenFormatHelper.parseAuthorizationHeader(header)` | member | `{ scheme, value }` with scheme lower-cased; first of a folded array; `null` without a value |
+| `tokenFormatHelper.isAccessToken(value, prefix)` | member | value starts with the prefix and is longer than it |
+| `tokenFormatHelper.displayOf(token, prefix)` | member | prefix + 8 characters of the secret |
+| `CreateAccessTokenSchema` | AJV schema | `name` 1–64, `scopes?` ≤ 32 items, `expiresIn?` integer seconds 60…366 days |
+| `AccessTokenParamsSchema` | AJV schema | `{ id }`, 1–128 characters |
+
+### Constants
+
+| Symbol | Value |
+|---|---|
+| `GUARD_AUTH_TOKEN` | `'guard:auth-token'` |
+| `AUTH_TOKEN_RESOURCE`, `AUTH_TOKEN_COLLECTION` | `'auth-token:token'`, `'access-token'` |
+| `AUTH_TOKEN_DEFAULT_PREFIX` | `'owl_'` |
+| `AUTH_TOKEN_SECRET_BYTES`, `AUTH_TOKEN_DISPLAY_LENGTH` | `24`, `8` |
+| `AUTH_TOKEN_TOUCH_INTERVAL` | 5 minutes in ms — how often `lastUsedAt` is written |
+| `AUTH_TOKEN_MAX_TTL` | 366 days in ms |
+| `AUTH_TOKEN_NAME_MAX` | `64` |
+| `authToken` | frozen route aliases `{ base, list, create, revoke }` (`'auth-token:*'`) |
+| `AUTH_TOKEN_SCHEME`, `BEARER_SCHEME` | `'auth-token'`, `'bearer'` (lower-cased, for comparison) |
+
+### Types
+
+| Symbol | Purpose |
+|---|---|
+| `AccessTokenRecord` | the stored record (hash, display, owner ids, scopes, role, dates, `audience?`) |
+| `AccessTokenView` | the record without `hash` — what a caller may see |
+| `CreateAccessToken` | `{ name, scopes?, expiresIn? }` — `expiresIn` in seconds |
+| `IssuedAccessToken` | `{ token, record }` |
+| `AccessTokenList`, `AccessTokenParams` | `{ items }`, `{ id }` |
+| `TokenCarrierOptions` | `{ token: string \| () => string \| Promise<string>, scheme?, onRejected? }` |
+| `AuthTokenEntrypointOptions`, `AuthTokenEntrypoints` | `makeAuthTokenEntrypoints` input and output |
+| `AuthorizationHeader`, `TokenFormatHelper` | parsed header and the format helper interface |
+
+## Common pitfalls
+
+- Do not use `extractAuthToken` from `@owlmeans/auth-common` for these tokens — it compares against
+  the upper-cased type and never matches `Bearer`; use `tokenFormatHelper.parseAuthorizationHeader`.
+- `expiresIn` is seconds, not days; omit it for "never" rather than sending `0`.
+- The plaintext is returned only by `create`; never store or log it. Lists show `display`.
+- Give each deployment its own prefix so two deployments never claim each other's tokens.
+- Pass a thunk as `token` in long-running processes so a reconfigured credential is picked up.
+- Do not add an update route: a token that can be widened after issuance is a grant nobody can
+  reason about.
+
+The `auth-token` skill covers the prefix rule, header parsing, the carrier guard and the management
+surface; the `server-auth-token` skill covers the store and the verifying guard.
+
+## Related packages
+
+- [`@owlmeans/server-auth-token`](../server-auth-token) — token store, verifying guard with audience admission, handlers
+- [`@owlmeans/web-auth-token`](../web-auth-token) — the token-management panel and hook
+- [`@owlmeans/server-oauth`](../server-oauth) — mints audience-scoped tokens through OAuth grants
+- [`@owlmeans/auth-common`](../auth-common) — `authMiddleware`, `DEFAULT_GUARD`
+- [`@owlmeans/cli-auth`](../cli-auth) — browser sign-in for a CLI, whose result a carrier guard can present
+- [`@owlmeans/entrypoint`](../entrypoint) — protocol declarations and `GuardService`
+
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
 
@@ -6,7 +169,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.20
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/auth-token",
-  "version": "0.1.18-rc.8",
-  "generatedAt": "2026-09-12T14:18:54.792Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.748Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/auth-token/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/auth-token
 
 **Layer:** Auth shared
-**Install:** `"@owlmeans/auth-token": "^0.1.18-rc.8"` in `dependencies`
+**Install:** `"@owlmeans/auth-token": "^0.1.18"` in `dependencies`
 
 The contract half of long-lived access tokens: the record shape, the route declarations, the
 format helpers, and one client-side guard that presents a token it was handed. The server half —
@@ -20,7 +20,7 @@ UI is `@owlmeans/web-auth-token`.
 | Export | Description |
 |--------|-------------|
 | `makeAuthTokenEntrypoints(opts?)` | The three routes (`list` GET, `create` POST, `revoke` DELETE `/:id`) under a `/tokens` base. `opts`: `parent`, `path`, `guard` |
-| `makeTokenCarrierGuard(alias, opts)` | A client `GuardService` that presents one token. `opts.token` is a value or a thunk; `opts.scheme` is `'auth-token'` (default) or `'bearer'` |
+| `makeTokenCarrierGuard(alias, opts)` | A client `GuardService` that presents one token. `opts.token` is a value or a thunk; `opts.scheme` is `'auth-token'` (default) or `'bearer'`; `opts.onRejected` hears a 401 |
 | `parseAuthorizationHeader(header)` | `{ scheme, value }` with the scheme lower-cased, or `null` |
 | `isAccessToken(value, prefix)` · `displayOf(token, prefix)` | Whether a value is one of this deployment's tokens; the half of it that may be shown again |
 | `CreateAccessTokenSchema` · `AccessTokenParamsSchema` | The ajv body/params filters |
@@ -39,6 +39,12 @@ the guard answers `match` only for a value that starts with it — so an access
 session bearer arrive under the same `Authorization` header without either guard shadowing the
 other, and two deployments never mistake each other's credentials for their own.
 
+**`AccessTokenRecord.audience?: string[]`** names the resources a token was issued FOR when it came
+through an OAuth grant (`@owlmeans/server-oauth`, RFC 8707 applied at OUR guard — the token is an
+opaque secret, not a JWT). Absent on every hand-minted token, which is admitted everywhere its scopes
+reach; a non-empty audience is admitted only by a guard whose `resources` intersect it (see
+[[server-auth-token]]).
+
 The plaintext exists exactly once, in the create response. What is stored is its hash; what a list
 shows forever after is `display` — the prefix plus 8 characters, enough to tell two of your own
 tokens apart and far too little to replay.
@@ -66,7 +72,14 @@ context.registerMiddleware(authMiddleware)
 
 There is no session, no refresh and no storage: the token is a long-lived credential the caller was
 handed. `opts.token` may be a thunk because a long-running process reads it from an environment
-variable and must not cache it past a reconfiguration.
+variable or a credentials file and must not cache it past a reconfiguration — or past a sign-in that
+has not happened yet.
+
+**The carrier answers `update()`.** On a 401 for a request that presented this guard's bearer,
+`@owlmeans/api` calls `service('<alias>').update(undefined)` to clear a browser session; a carrier
+with no `update` made that a bare `TypeError` instead of the auth failure already being reported. The
+carrier's `update` is a no-op that calls `opts.onRejected` — the hook a credential holder uses to
+forget a dead token and sign in again (or to report it, when an operator supplied it by hand).
 
 ## The management surface is deliberately not a CRUD
 
@@ -92,7 +105,8 @@ sending a zero.
 
 ## Related
 
-- [[server-auth-token]] — the store, the verifying guard, the handlers and the coguard
+- [[server-auth-token]] — the store, the verifying guard (audience admission), issuance, the handlers and the coguard
+- [[oauth]] — the OAuth vocabulary that mints audience-scoped tokens
 - [[web-auth-token]] — the management panel and its hook
 - [[auth-protocol]] — where long-lived tokens sit among the other authentication paths
 - [[auth-common]] — `authMiddleware`, `DEFAULT_GUARD`, `extractAuthToken`

package/build/carrier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"carrier.d.ts","sourceRoot":"","sources":["../src/carrier.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAExD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,UAAW,MAAM,QAAQ,mBAAmB,KAAG,YAsBhF,CAAA"}
+{"version":3,"file":"carrier.d.ts","sourceRoot":"","sources":["../src/carrier.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAExD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,UAAW,MAAM,QAAQ,mBAAmB,KAAG,YA8BhF,CAAA"}

package/build/carrier.js

@@ -26,6 +26,8 @@ export const makeTokenCarrierGuard = (alias, opts) => {
             return token == null ? null : `${scheme} ${token}`;
         },
     }, service => async () => { service.initialized = true; });
+    service.update =
+        async () => { await opts.onRejected?.(); };
     return service;
 };
 //# sourceMappingURL=carrier.js.map

package/build/carrier.js.map

@@ -1 +1 @@
-{"version":3,"file":"carrier.js","sourceRoot":"","sources":["../src/carrier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG9D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAa,EAAE,IAAyB,EAAgB,EAAE;IAC9F,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,WAAW,EAAE,CAAA;IAEzF,MAAM,OAAO,GAAG,KAAK,IAA4B,EAAE;QACjD,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAA;QAEhF,OAAO,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAA;IACrD,CAAC,CAAA;IAED,MAAM,OAAO,GAAiB,aAAa,CAAe,KAAK,EAAE;QAC/D,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM,OAAO,EAAE,IAAI,IAAI;QAE1C,MAAM,EAAE,KAAK,IAAO,EAAE,CAAC,KAAK,CAAM;QAElC,aAAa,EAAE,KAAK,IAAI,EAAE;YACxB,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAA;YAE7B,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,EAAE,CAAA;QACpD,CAAC;KACF,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAA,CAAC,CAAC,CAAC,CAAA;IAEzD,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}
+{"version":3,"file":"carrier.js","sourceRoot":"","sources":["../src/carrier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG9D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAa,EAAE,IAAyB,EAAgB,EAAE;IAC9F,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,WAAW,EAAE,CAAA;IAEzF,MAAM,OAAO,GAAG,KAAK,IAA4B,EAAE;QACjD,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAA;QAEhF,OAAO,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAA;IACrD,CAAC,CAAA;IAED,MAAM,OAAO,GAAiB,aAAa,CAAe,KAAK,EAAE;QAC/D,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM,OAAO,EAAE,IAAI,IAAI;QAE1C,MAAM,EAAE,KAAK,IAAO,EAAE,CAAC,KAAK,CAAM;QAElC,aAAa,EAAE,KAAK,IAAI,EAAE;YACxB,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAA;YAE7B,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,EAAE,CAAA;QACpD,CAAC;KACF,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAA,CAAC,CAAC,CAAC,CAOxD;IAAC,OAAmF,CAAC,MAAM;QAC1F,KAAK,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,EAAE,CAAA,CAAC,CAAC,CAAA;IAE3C,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}

package/build/format/types.d.ts

@@ -0,0 +1,27 @@
+/** An `Authorization` header taken apart: the scheme lower-cased, the value trimmed. */
+export interface AuthorizationHeader {
+    scheme: string;
+    value: string;
+}
+/** How an access token is recognised on the wire and shown back to a person. */
+export interface TokenFormatHelper {
+    /**
+     * Split an `Authorization` header into its scheme and its value.
+     *
+     * Deliberately NOT `extractAuthToken` from `@owlmeans/auth-common`: that compares the prefix
+     * against `type.toUpperCase()`, so it matches `AUTH-TOKEN` and can never match `Bearer` — the
+     * exact spelling every third-party client sends. The scheme comes back lower-cased so a caller
+     * compares once.
+     */
+    parseAuthorizationHeader: (header: string | string[] | undefined) => AuthorizationHeader | null;
+    /** Whether a value looks like an access token this deployment issued. */
+    isAccessToken: (value: string | null | undefined, prefix: string) => boolean;
+    /**
+     * The half of a token that may be shown again.
+     *
+     * Prefix plus the first characters of the secret. Enough to tell two tokens apart in a list, and
+     * far short of anything that could be replayed.
+     */
+    displayOf: (token: string, prefix: string) => string;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/format/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/format/types.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,wBAAwB,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,KAAK,mBAAmB,GAAG,IAAI,CAAA;IAC/F,yEAAyE;IACzE,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAA;IAC5E;;;;;OAKG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAA;CACrD"}

package/build/format/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/format/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/format/types.ts"],"names":[],"mappings":""}

package/build/format.d.ts

@@ -1,22 +1,4 @@
-/**
- * Split an `Authorization` header into its scheme and its value.
- *
- * Deliberately NOT `extractAuthToken` from `@owlmeans/auth-common`: that compares the prefix
- * against `type.toUpperCase()`, so it matches `AUTH-TOKEN` and can never match `Bearer` — the
- * exact spelling every third-party client sends. The scheme comes back lower-cased so a caller
- * compares once.
- */
-export declare const parseAuthorizationHeader: (header: string | string[] | undefined) => {
-    scheme: string;
-    value: string;
-} | null;
-/** Whether a value looks like an access token this deployment issued. */
-export declare const isAccessToken: (value: string | null | undefined, prefix: string) => boolean;
-/**
- * The half of a token that may be shown again.
- *
- * Prefix plus the first characters of the secret. Enough to tell two tokens apart in a list, and
- * far short of anything that could be replayed.
- */
-export declare const displayOf: (token: string, prefix: string) => string;
+import type { TokenFormatHelper } from './format/types.js';
+export declare const createTokenFormatHelper: () => TokenFormatHelper;
+export declare const tokenFormatHelper: TokenFormatHelper;
 //# sourceMappingURL=format.d.ts.map

package/build/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,WAC3B,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,KACpC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAatC,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,aAAa,UAAW,MAAM,GAAG,IAAI,GAAG,SAAS,UAAU,MAAM,KAAG,OACN,CAAA;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,SAAS,UAAW,MAAM,UAAU,MAAM,KAAG,MAIzD,CAAA"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAuB,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE/E,eAAO,MAAM,uBAAuB,QAAO,iBA4B1C,CAAA;AAED,eAAO,MAAM,iBAAiB,mBAA4B,CAAA"}

package/build/format.js

@@ -1,36 +1,25 @@
 import { AUTH_TOKEN_DISPLAY_LENGTH } from './consts.js';
-/**
- * Split an `Authorization` header into its scheme and its value.
- *
- * Deliberately NOT `extractAuthToken` from `@owlmeans/auth-common`: that compares the prefix
- * against `type.toUpperCase()`, so it matches `AUTH-TOKEN` and can never match `Bearer` — the
- * exact spelling every third-party client sends. The scheme comes back lower-cased so a caller
- * compares once.
- */
-export const parseAuthorizationHeader = (header) => {
-    const raw = Array.isArray(header) ? header[0] : header;
-    if (raw == null)
-        return null;
-    const trimmed = raw.trim();
-    const space = trimmed.indexOf(' ');
-    if (space < 1)
-        return null;
-    const scheme = trimmed.slice(0, space).toLowerCase();
-    const value = trimmed.slice(space + 1).trim();
-    if (value.length < 1)
-        return null;
-    return { scheme, value };
-};
-/** Whether a value looks like an access token this deployment issued. */
-export const isAccessToken = (value, prefix) => value != null && value.length > prefix.length && value.startsWith(prefix);
-/**
- * The half of a token that may be shown again.
- *
- * Prefix plus the first characters of the secret. Enough to tell two tokens apart in a list, and
- * far short of anything that could be replayed.
- */
-export const displayOf = (token, prefix) => {
-    const secret = token.startsWith(prefix) ? token.slice(prefix.length) : token;
-    return `${prefix}${secret.slice(0, AUTH_TOKEN_DISPLAY_LENGTH)}`;
+export const createTokenFormatHelper = () => {
+    const parseAuthorizationHeader = (header) => {
+        const raw = Array.isArray(header) ? header[0] : header;
+        if (raw == null)
+            return null;
+        const trimmed = raw.trim();
+        const space = trimmed.indexOf(' ');
+        if (space < 1)
+            return null;
+        const scheme = trimmed.slice(0, space).toLowerCase();
+        const value = trimmed.slice(space + 1).trim();
+        if (value.length < 1)
+            return null;
+        return { scheme, value };
+    };
+    const isAccessToken = (value, prefix) => value != null && value.length > prefix.length && value.startsWith(prefix);
+    const displayOf = (token, prefix) => {
+        const secret = token.startsWith(prefix) ? token.slice(prefix.length) : token;
+        return `${prefix}${secret.slice(0, AUTH_TOKEN_DISPLAY_LENGTH)}`;
+    };
+    return { parseAuthorizationHeader, isAccessToken, displayOf };
 };
+export const tokenFormatHelper = createTokenFormatHelper();
 //# sourceMappingURL=format.js.map

package/build/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAEvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,MAAqC,EACK,EAAE;IAC5C,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IACtD,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IAE5B,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;IAC1B,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAClC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAE1B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;IACpD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAC7C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAEjC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC1B,CAAC,CAAA;AAED,yEAAyE;AACzE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAgC,EAAE,MAAc,EAAW,EAAE,CACzF,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;AAE3E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,MAAc,EAAU,EAAE;IACjE,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;IAE5E,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,yBAAyB,CAAC,EAAE,CAAA;AACjE,CAAC,CAAA"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAGvD,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAsB,EAAE;IAC7D,MAAM,wBAAwB,GAAG,CAC/B,MAAqC,EACT,EAAE;QAC9B,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;QACtD,IAAI,GAAG,IAAI,IAAI;YAAE,OAAO,IAAI,CAAA;QAE5B,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;QAC1B,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAA;QAE1B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;QACpD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC7C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAA;QAEjC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;IAC1B,CAAC,CAAA;IAED,MAAM,aAAa,GAAG,CAAC,KAAgC,EAAE,MAAc,EAAW,EAAE,CAClF,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;IAE3E,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,MAAc,EAAU,EAAE;QAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;QAE5E,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,yBAAyB,CAAC,EAAE,CAAA;IACjE,CAAC,CAAA;IAED,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,SAAS,EAAE,CAAA;AAC/D,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,EAAE,CAAA"}

package/build/index.d.ts

@@ -4,4 +4,5 @@ export * from './entrypoints.js';
 export * from './format.js';
 export * from './carrier.js';
 export type * from './types.js';
+export type * from './format/types.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,mBAAmB,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,mBAAmB,CAAA"}

package/build/types.d.ts

@@ -1,6 +1,7 @@
 import type { AuthRole } from '@owlmeans/auth';
 import type { ResourceRecord } from '@owlmeans/resource';
 import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint';
+import type { RouteParent } from '@owlmeans/route';
 /**
  * One long-lived access token, as stored.
  *
@@ -30,9 +31,22 @@ export interface AccessTokenRecord extends ResourceRecord {
     expiresAt?: Date;
     /** Set once and never unset. A revoked token is kept so its display name still resolves. */
     revokedAt?: Date;
+    /**
+     * Resources this token was issued FOR, when it was issued through an OAuth grant
+     * (`@owlmeans/server-oauth`).
+     *
+     * Absent for every token minted by hand through `createAccessToken` — those are admitted
+     * everywhere the caller's scopes reach, exactly as before this field existed. A non-empty
+     * audience narrows that: a guard configured with `resources` admits the token only when the
+     * two lists intersect, so a token minted for the `/mcp` connector cannot also drive the
+     * ordinary REST API, and vice versa (RFC 8707's audience-restriction, applied at OUR guard
+     * rather than by decoding a JWT audience claim, because this token is an opaque secret).
+     */
+    audience?: string[];
 }
 /** What a caller may see. The hash never leaves the server. */
-export type AccessTokenView = Omit<AccessTokenRecord, 'hash'>;
+export interface AccessTokenView extends Omit<AccessTokenRecord, 'hash'> {
+}
 export interface CreateAccessToken {
     name: string;
     /** A subset of the caller's own scopes. Defaults to all of them. */
@@ -61,10 +75,18 @@ export interface AccessTokenParams {
 export interface TokenCarrierOptions {
     token: string | (() => string | Promise<string>);
     scheme?: 'auth-token' | 'bearer';
+    /**
+     * Called when the platform rejects a request that presented this credential — `@owlmeans/api`
+     * reaches for `AuthService.update(undefined)` on such a 401, and a carrier with none of that
+     * machinery answers with a no-op unless this is given. A credential holder wires it to whatever
+     * it does about a dead token: sign in again if it minted the token itself, or report the
+     * problem rather than silently trying another identity if an operator supplied it by hand.
+     */
+    onRejected?: () => void | Promise<void>;
 }
 export interface AuthTokenEntrypointOptions {
-    /** The entrypoint the token routes hang under. */
-    parent?: string;
+    /** The entrypoint the token routes hang under. A parent protocol is preferred; strings remain adapter input. */
+    parent?: RouteParent;
     /** Path of the token base, relative to the parent. Defaults to `/tokens`. */
     path?: string;
     /** The guard the base carries when it has no parent to inherit one from. */

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAEtF;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAA;IACZ,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAA;IACf,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,IAAI,EAAE,QAAQ,CAAA;IACd,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,CAAC,EAAE,IAAI,CAAA;IAChB,mFAAmF;IACnF,UAAU,CAAC,EAAE,IAAI,CAAA;IACjB,SAAS,CAAC,EAAE,IAAI,CAAA;IAChB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,IAAI,CAAA;CACjB;AAED,+DAA+D;AAC/D,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAA;AAE7D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,eAAe,CAAA;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;IAChD,MAAM,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAA;CACjC;AAED,MAAM,WAAW,0BAA0B;IACzC,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;IAChD,IAAI,EAAE,kBAAkB,CAAC,WAAW,EAAE,eAAe,CAAC,CAAA;IACtD,MAAM,EAAE,kBAAkB,CAAC;QAAE,IAAI,EAAE,iBAAiB,CAAA;KAAE,EAAE,iBAAiB,CAAC,CAAA;IAC1E,MAAM,EAAE,kBAAkB,CAAC;QAAE,MAAM,EAAE,iBAAiB,CAAA;KAAE,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC1E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AACtF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAA;IACZ,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAA;IACf,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,IAAI,EAAE,QAAQ,CAAA;IACd,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,CAAC,EAAE,IAAI,CAAA;IAChB,mFAAmF;IACnF,UAAU,CAAC,EAAE,IAAI,CAAA;IACjB,SAAS,CAAC,EAAE,IAAI,CAAA;IAChB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,IAAI,CAAA;IAChB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC;CAAG;AAE3E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,eAAe,CAAA;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;IAChD,MAAM,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAA;IAChC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,0BAA0B;IACzC,gHAAgH;IAChH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;IAChD,IAAI,EAAE,kBAAkB,CAAC,WAAW,EAAE,eAAe,CAAC,CAAA;IACtD,MAAM,EAAE,kBAAkB,CAAC;QAAE,IAAI,EAAE,iBAAiB,CAAA;KAAE,EAAE,iBAAiB,CAAC,CAAA;IAC1E,MAAM,EAAE,kBAAkB,CAAC;QAAE,MAAM,EAAE,iBAAiB,CAAA;KAAE,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC1E"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@owlmeans/auth-token",
-  "version": "0.1.18-rc.8",
+  "version": "0.1.18",
   "license": "MIT",
-  "description": "Long-lived access tokens (API keys) on the OwlMeans auth rails — the record shape, the token format, the management entrypoints and the client-side carrier guard.",
+  "description": "Long-lived access tokens (API keys) on the OwlMeans auth rails \u2014 the record shape, the token format, the management entrypoints and the client-side carrier guard.",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
@@ -23,16 +23,16 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.17",
-    "@owlmeans/context": "^0.1.18-rc.16",
-    "@owlmeans/entrypoint": "^0.1.18-rc.19",
-    "@owlmeans/resource": "^0.1.18-rc.17",
-    "@owlmeans/route": "^0.1.18-rc.17"
+    "@owlmeans/auth": "^0.1.18",
+    "@owlmeans/context": "^0.1.18",
+    "@owlmeans/entrypoint": "^0.1.18",
+    "@owlmeans/resource": "^0.1.18",
+    "@owlmeans/route": "^0.1.18"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@types/bun": "^1.4.0",
-    "ajv": "^8.17.1",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@types/bun": "^1.4.2",
+    "ajv": "^8.20.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/carrier.ts

@@ -36,5 +36,13 @@ export const makeTokenCarrierGuard = (alias: string, opts: TokenCarrierOptions):
     },
   }, service => async () => { service.initialized = true })
 
+  // `@owlmeans/api` calls `context.service<AuthService>(alias).update(undefined)` on a 401 for a
+  // request that presented this guard's bearer — an ordinary browser session clears itself there,
+  // and a carrier with no `update` at all made that call throw a bare `TypeError` instead of the
+  // auth failure it was already reporting. There is no session to clear here, so this is a no-op
+  // unless the caller asked to hear about it through `onRejected`.
+  ;(service as GuardService & { update: (token: string | undefined) => Promise<void> }).update =
+    async () => { await opts.onRejected?.() }
+
   return service
 }

package/src/format/types.ts

@@ -0,0 +1,27 @@
+/** An `Authorization` header taken apart: the scheme lower-cased, the value trimmed. */
+export interface AuthorizationHeader {
+  scheme: string
+  value: string
+}
+
+/** How an access token is recognised on the wire and shown back to a person. */
+export interface TokenFormatHelper {
+  /**
+   * Split an `Authorization` header into its scheme and its value.
+   *
+   * Deliberately NOT `extractAuthToken` from `@owlmeans/auth-common`: that compares the prefix
+   * against `type.toUpperCase()`, so it matches `AUTH-TOKEN` and can never match `Bearer` — the
+   * exact spelling every third-party client sends. The scheme comes back lower-cased so a caller
+   * compares once.
+   */
+  parseAuthorizationHeader: (header: string | string[] | undefined) => AuthorizationHeader | null
+  /** Whether a value looks like an access token this deployment issued. */
+  isAccessToken: (value: string | null | undefined, prefix: string) => boolean
+  /**
+   * The half of a token that may be shown again.
+   *
+   * Prefix plus the first characters of the secret. Enough to tell two tokens apart in a list, and
+   * far short of anything that could be replayed.
+   */
+  displayOf: (token: string, prefix: string) => string
+}

package/src/format.ts

@@ -1,42 +1,34 @@
 import { AUTH_TOKEN_DISPLAY_LENGTH } from './consts.js'
+import type { AuthorizationHeader, TokenFormatHelper } from './format/types.js'
 
-/**
- * Split an `Authorization` header into its scheme and its value.
- *
- * Deliberately NOT `extractAuthToken` from `@owlmeans/auth-common`: that compares the prefix
- * against `type.toUpperCase()`, so it matches `AUTH-TOKEN` and can never match `Bearer` — the
- * exact spelling every third-party client sends. The scheme comes back lower-cased so a caller
- * compares once.
- */
-export const parseAuthorizationHeader = (
-  header: string | string[] | undefined
-): { scheme: string, value: string } | null => {
-  const raw = Array.isArray(header) ? header[0] : header
-  if (raw == null) return null
-
-  const trimmed = raw.trim()
-  const space = trimmed.indexOf(' ')
-  if (space < 1) return null
-
-  const scheme = trimmed.slice(0, space).toLowerCase()
-  const value = trimmed.slice(space + 1).trim()
-  if (value.length < 1) return null
-
-  return { scheme, value }
-}
+export const createTokenFormatHelper = (): TokenFormatHelper => {
+  const parseAuthorizationHeader = (
+    header: string | string[] | undefined
+  ): AuthorizationHeader | null => {
+    const raw = Array.isArray(header) ? header[0] : header
+    if (raw == null) return null
+
+    const trimmed = raw.trim()
+    const space = trimmed.indexOf(' ')
+    if (space < 1) return null
+
+    const scheme = trimmed.slice(0, space).toLowerCase()
+    const value = trimmed.slice(space + 1).trim()
+    if (value.length < 1) return null
 
-/** Whether a value looks like an access token this deployment issued. */
-export const isAccessToken = (value: string | null | undefined, prefix: string): boolean =>
-  value != null && value.length > prefix.length && value.startsWith(prefix)
+    return { scheme, value }
+  }
 
-/**
- * The half of a token that may be shown again.
- *
- * Prefix plus the first characters of the secret. Enough to tell two tokens apart in a list, and
- * far short of anything that could be replayed.
- */
-export const displayOf = (token: string, prefix: string): string => {
-  const secret = token.startsWith(prefix) ? token.slice(prefix.length) : token
+  const isAccessToken = (value: string | null | undefined, prefix: string): boolean =>
+    value != null && value.length > prefix.length && value.startsWith(prefix)
 
-  return `${prefix}${secret.slice(0, AUTH_TOKEN_DISPLAY_LENGTH)}`
+  const displayOf = (token: string, prefix: string): string => {
+    const secret = token.startsWith(prefix) ? token.slice(prefix.length) : token
+
+    return `${prefix}${secret.slice(0, AUTH_TOKEN_DISPLAY_LENGTH)}`
+  }
+
+  return { parseAuthorizationHeader, isAccessToken, displayOf }
 }
+
+export const tokenFormatHelper = createTokenFormatHelper()

package/src/index.ts

@@ -4,3 +4,4 @@ export * from './entrypoints.js'
 export * from './format.js'
 export * from './carrier.js'
 export type * from './types.js'
+export type * from './format/types.js'

package/src/types.ts

@@ -1,6 +1,7 @@
 import type { AuthRole } from '@owlmeans/auth'
 import type { ResourceRecord } from '@owlmeans/resource'
 import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint'
+import type { RouteParent } from '@owlmeans/route'
 
 /**
  * One long-lived access token, as stored.
@@ -31,10 +32,22 @@ export interface AccessTokenRecord extends ResourceRecord {
   expiresAt?: Date
   /** Set once and never unset. A revoked token is kept so its display name still resolves. */
   revokedAt?: Date
+  /**
+   * Resources this token was issued FOR, when it was issued through an OAuth grant
+   * (`@owlmeans/server-oauth`).
+   *
+   * Absent for every token minted by hand through `createAccessToken` — those are admitted
+   * everywhere the caller's scopes reach, exactly as before this field existed. A non-empty
+   * audience narrows that: a guard configured with `resources` admits the token only when the
+   * two lists intersect, so a token minted for the `/mcp` connector cannot also drive the
+   * ordinary REST API, and vice versa (RFC 8707's audience-restriction, applied at OUR guard
+   * rather than by decoding a JWT audience claim, because this token is an opaque secret).
+   */
+  audience?: string[]
 }
 
 /** What a caller may see. The hash never leaves the server. */
-export type AccessTokenView = Omit<AccessTokenRecord, 'hash'>
+export interface AccessTokenView extends Omit<AccessTokenRecord, 'hash'> {}
 
 export interface CreateAccessToken {
   name: string
@@ -68,11 +81,19 @@ export interface AccessTokenParams {
 export interface TokenCarrierOptions {
   token: string | (() => string | Promise<string>)
   scheme?: 'auth-token' | 'bearer'
+  /**
+   * Called when the platform rejects a request that presented this credential — `@owlmeans/api`
+   * reaches for `AuthService.update(undefined)` on such a 401, and a carrier with none of that
+   * machinery answers with a no-op unless this is given. A credential holder wires it to whatever
+   * it does about a dead token: sign in again if it minted the token itself, or report the
+   * problem rather than silently trying another identity if an operator supplied it by hand.
+   */
+  onRejected?: () => void | Promise<void>
 }
 
 export interface AuthTokenEntrypointOptions {
-  /** The entrypoint the token routes hang under. */
-  parent?: string
+  /** The entrypoint the token routes hang under. A parent protocol is preferred; strings remain adapter input. */
+  parent?: RouteParent
   /** Path of the token base, relative to the parent. Defaults to `/tokens`. */
   path?: string
   /** The guard the base carries when it has no parent to inherit one from. */

package/tests/carrier.spec.ts

@@ -46,4 +46,24 @@ describe('@owlmeans/auth-token — the client carrier guard', () => {
     expect(await guard.authenticated()).toBeNull()
     expect(await guard.match({} as any, {} as any)).toBe(false)
   })
+
+  test('answers update() rather than throwing — the call `@owlmeans/api` makes on a 401', async () => {
+    const guard = makeTokenCarrierGuard('carrier', { token: 'owl_secret' }) as GuardService & {
+      update: (token: string | undefined) => Promise<void>
+    }
+    await contextWith(guard)
+
+    await expect(guard.update(undefined)).resolves.toBeUndefined()
+  })
+
+  test('update() calls onRejected, so a credential holder can act on a dead token', async () => {
+    let called = false
+    const guard = makeTokenCarrierGuard('carrier', {
+      token: 'owl_secret', onRejected: () => { called = true },
+    }) as GuardService & { update: (token: string | undefined) => Promise<void> }
+    await contextWith(guard)
+
+    await guard.update(undefined)
+    expect(called).toBe(true)
+  })
 })

package/tests/format.spec.ts

@@ -1,43 +1,43 @@
 import { describe, expect, test } from 'bun:test'
-import { displayOf, isAccessToken, parseAuthorizationHeader } from '../src/format.js'
+import { tokenFormatHelper } from '../src/format.js'
 import { AUTH_TOKEN_DEFAULT_PREFIX } from '../src/consts.js'
 
 describe('@owlmeans/auth-token — Authorization parsing', () => {
   test('lower-cases the scheme so Bearer and BEARER are one answer', () => {
-    expect(parseAuthorizationHeader('Bearer owl_abc')).toEqual({ scheme: 'bearer', value: 'owl_abc' })
-    expect(parseAuthorizationHeader('BEARER owl_abc')?.scheme).toBe('bearer')
-    expect(parseAuthorizationHeader('AUTH-TOKEN owl_abc')?.scheme).toBe('auth-token')
+    expect(tokenFormatHelper.parseAuthorizationHeader('Bearer owl_abc')).toEqual({ scheme: 'bearer', value: 'owl_abc' })
+    expect(tokenFormatHelper.parseAuthorizationHeader('BEARER owl_abc')?.scheme).toBe('bearer')
+    expect(tokenFormatHelper.parseAuthorizationHeader('AUTH-TOKEN owl_abc')?.scheme).toBe('auth-token')
   })
 
   test('takes the first header when a proxy folded several', () => {
-    expect(parseAuthorizationHeader(['Bearer one', 'Bearer two'])?.value).toBe('one')
+    expect(tokenFormatHelper.parseAuthorizationHeader(['Bearer one', 'Bearer two'])?.value).toBe('one')
   })
 
   test('answers null for anything that is not a scheme and a value', () => {
-    expect(parseAuthorizationHeader(undefined)).toBeNull()
-    expect(parseAuthorizationHeader('')).toBeNull()
-    expect(parseAuthorizationHeader('Bearer')).toBeNull()
-    expect(parseAuthorizationHeader('Bearer   ')).toBeNull()
-    expect(parseAuthorizationHeader(' leadingspace')).toBeNull()
+    expect(tokenFormatHelper.parseAuthorizationHeader(undefined)).toBeNull()
+    expect(tokenFormatHelper.parseAuthorizationHeader('')).toBeNull()
+    expect(tokenFormatHelper.parseAuthorizationHeader('Bearer')).toBeNull()
+    expect(tokenFormatHelper.parseAuthorizationHeader('Bearer   ')).toBeNull()
+    expect(tokenFormatHelper.parseAuthorizationHeader(' leadingspace')).toBeNull()
   })
 
   test('keeps a value that itself contains spaces', () => {
-    expect(parseAuthorizationHeader('Bearer a b c')?.value).toBe('a b c')
+    expect(tokenFormatHelper.parseAuthorizationHeader('Bearer a b c')?.value).toBe('a b c')
   })
 })
 
 describe('@owlmeans/auth-token — token shape', () => {
   test('claims only a value carrying the prefix', () => {
-    expect(isAccessToken('owl_abcdef', AUTH_TOKEN_DEFAULT_PREFIX)).toBe(true)
-    expect(isAccessToken('vib_abcdef', AUTH_TOKEN_DEFAULT_PREFIX)).toBe(false)
-    expect(isAccessToken('abcdef', AUTH_TOKEN_DEFAULT_PREFIX)).toBe(false)
+    expect(tokenFormatHelper.isAccessToken('owl_abcdef', AUTH_TOKEN_DEFAULT_PREFIX)).toBe(true)
+    expect(tokenFormatHelper.isAccessToken('vib_abcdef', AUTH_TOKEN_DEFAULT_PREFIX)).toBe(false)
+    expect(tokenFormatHelper.isAccessToken('abcdef', AUTH_TOKEN_DEFAULT_PREFIX)).toBe(false)
     // The prefix alone is not a token — there is no secret behind it.
-    expect(isAccessToken(AUTH_TOKEN_DEFAULT_PREFIX, AUTH_TOKEN_DEFAULT_PREFIX)).toBe(false)
-    expect(isAccessToken(null, AUTH_TOKEN_DEFAULT_PREFIX)).toBe(false)
+    expect(tokenFormatHelper.isAccessToken(AUTH_TOKEN_DEFAULT_PREFIX, AUTH_TOKEN_DEFAULT_PREFIX)).toBe(false)
+    expect(tokenFormatHelper.isAccessToken(null, AUTH_TOKEN_DEFAULT_PREFIX)).toBe(false)
   })
 
   test('the display form keeps the prefix and eight characters of the secret', () => {
-    const display = displayOf('owl_ABCDEFGHIJKLMNOP', 'owl_')
+    const display = tokenFormatHelper.displayOf('owl_ABCDEFGHIJKLMNOP', 'owl_')
     expect(display).toBe('owl_ABCDEFGH')
     // Short enough to be useless, long enough to tell two of a person's tokens apart.
     expect(display.length).toBeLessThan('owl_ABCDEFGHIJKLMNOP'.length)