@owlmeans/auth-token 0.1.18-rc.16 → 0.1.18-rc.17

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/auth-token",
-  "version": "0.1.18-rc.16",
-  "generatedAt": "2026-09-17T08:16:11.235Z",
+  "version": "0.1.18-rc.17",
+  "generatedAt": "2026-09-18T18:24:55.975Z",
   "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.16"` in `dependencies`
+**Install:** `"@owlmeans/auth-token": "^0.1.18-rc.17"` 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/types.d.ts

@@ -31,6 +31,18 @@ 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'>;
@@ -62,6 +74,14 @@ 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. A parent protocol is preferred; strings remain adapter input. */

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;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;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,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"}
+{"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,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;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,6 +1,6 @@
 {
   "name": "@owlmeans/auth-token",
-  "version": "0.1.18-rc.16",
+  "version": "0.1.18-rc.17",
   "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.",
   "type": "module",

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/types.ts

@@ -32,6 +32,18 @@ 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. */
@@ -69,6 +81,14 @@ 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 {

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)
+  })
 })