@owlmeans/server-auth-token 0.1.18-rc.33 → 0.1.18-rc.34

package/README.md

@@ -1,3 +1,179 @@
+# @owlmeans/server-auth-token
+
+The server half of long-lived access tokens: a MongoDB token store, a guard that verifies a
+presented token and turns it into the same `Auth` payload a browser session produces, the
+list / create / revoke handlers, a shared issuer for other minting paths (an OAuth token endpoint),
+and a coguard helper that admits a token on every already-guarded route. A backend uses it when API
+clients, CLIs or coding agents should call the same routes a signed-in person does. The token
+format, routes and record types live in `@owlmeans/auth-token`; the browser management panel is
+`@owlmeans/web-auth-token`; issuing tokens through an OAuth grant is `@owlmeans/server-oauth`, which
+calls this package's issuer.
+
+## Installation
+
+```bash
+bun add @owlmeans/server-auth-token@^0.1.18-rc.34
+```
+
+## Concepts
+
+- **Access token** — `<prefix><base58 of 24 random bytes>`; the prefix defaults to `owl_`. The
+  plaintext is returned once at creation; the store keeps only its SHA-256 `hash` and a short
+  `display` form.
+- **Guard, not authentication** — the guard verifies what arrives and resolves an `Auth` with
+  `type: AuthroizationType.AuthToken`; `authenticated()` always returns `null`, nothing is exchanged.
+- **Prefix claim** — the guard matches only an `Authorization` value with the `AUTH-TOKEN` or
+  `Bearer` scheme that carries the deployment's prefix, so it coexists with other bearer guards.
+- **Scope intersection** — on every request the token's scopes are intersected with its identity
+  profile's; a missing or expired profile refuses the token.
+- **Audience** — a token minted through OAuth carries `audience`; a guard configured with
+  `resources` refuses a token whose audience does not intersect them. Without `resources`, every
+  token is admitted.
+- **Deny list** — `denyAliases` names routes the guard never claims, so an interactive-only route
+  stays a 401 for a token even when the guard is inherited.
+
+## Usage
+
+### Register the store and the guard
+
+```typescript
+import { GUARD_AUTH_TOKEN } from '@owlmeans/auth-token'
+import { AUTH_IDENTITY_DB_ALIAS } from '@owlmeans/server-auth-identity'
+import { appendAuthTokenGuard, appendAuthTokenResources } from '@owlmeans/server-auth-token'
+
+appendAuthTokenResources(context, AUTH_IDENTITY_DB_ALIAS)   // same dbAlias as the identity resources
+appendAuthTokenGuard(context, GUARD_AUTH_TOKEN, {
+  prefix: 'vib_',                                           // also written to cfg.authToken.prefix
+  denyAliases: [protocols.tokens.create.alias, protocols.tokens.revoke.alias, checkoutProtocol.alias],
+})
+```
+
+### Bind the token routes
+
+```typescript
+import { makeAuthTokenEntrypoints } from '@owlmeans/auth-token'
+import { bind } from '@owlmeans/server-entrypoint'
+import { createAccessToken, listAccessTokens, revokeAccessToken } from '@owlmeans/server-auth-token'
+
+const tokens = makeAuthTokenEntrypoints({ parent: account.base })
+
+context.registerEntrypoints([
+  bind(tokens.list, listAccessTokens(tokens.list)),
+  bind(tokens.create, createAccessToken(tokens.create)),
+  bind(tokens.revoke, revokeAccessToken(tokens.revoke)),
+])
+```
+
+`revokeAccessToken(protocol, { allowAccessTokens: true })` lets a token revoke the same person's
+tokens (for an agent-facing surface); ownership is still checked and minting stays refused.
+
+### Admit tokens on every guarded route
+
+```typescript
+import { withAuthTokenCoguard } from '@owlmeans/server-auth-token'
+
+export const guardedProtocols = withAuthTokenCoguard(appProtocols)   // before creating bindings
+```
+
+The coguard is appended after each protocol's existing guards; protocols without a guard are left
+alone, and running it twice changes nothing.
+
+### Restrict a surface to tokens issued for it
+
+```typescript
+appendAuthTokenGuard(context, 'guard:mcp-token', {
+  resources: ctx => [mcpResourceUri(ctx)],                   // app function, resolved per request
+})
+```
+
+### Mint from another flow
+
+```typescript
+import { accessTokenIssuerOf, refuseTokenAuth } from '@owlmeans/server-auth-token'
+
+refuseTokenAuth(req, 'token-mint')   // a token may never mint a token
+const issued = await accessTokenIssuerOf(context).issueAccessToken(
+  { entityId, userId, profileId, role, scopes: ownScopes },
+  { name: 'MCP connector', scopes: ['*'], expiresIn: 3600, audience: [resourceUri] },
+)
+// issued.token is the plaintext, shown once; issued.record is the hash-free view
+```
+
+## API
+
+### Registration and guard
+
+| Symbol | Purpose |
+|---|---|
+| `appendAuthTokenResources(ctx, dbAlias?)` | Registers `makeAccessTokenResource(dbAlias)` |
+| `appendAuthTokenGuard(ctx, alias?, opts?)` | Registers the guard (default alias `GUARD_AUTH_TOKEN`); writes `opts.prefix` into `cfg.authToken.prefix` |
+| `makeAuthTokenGuard(alias?, opts?)` | The `GuardService` |
+| `makeAccessTokenResource(dbAlias?)` | Mongo resource at `AUTH_TOKEN_RESOURCE`, collection `access-token`; indexes `hash` (unique), `owner` (`entityId`, `profileId`), `expiresAt` (sparse) |
+| `withAuthTokenCoguard(tree, guard?)` | Same-shaped protocol tree with the token guard appended to every guarded protocol |
+| `prefixOf(context, opts?)` | Prefix from guard options, then `cfg.authToken.prefix`, then `owl_` |
+
+### Handlers and issuance
+
+| Symbol | Purpose |
+|---|---|
+| `listAccessTokens(protocol)` | The caller's tokens in the caller's organization entity, newest first, without hashes |
+| `createAccessToken(protocol)` | Mints a token from the session; refuses token auth; scopes may only narrow |
+| `revokeAccessToken(protocol, opts?)` | Sets `revokedAt` on the caller's own token; idempotent; a foreign id answers like an unknown one |
+| `accessTokenIssuerOf(ctx).issueAccessToken(subject, request)` | The shared minting path; `expiresIn` is clamped to `AUTH_TOKEN_MAX_TTL` |
+| `makeAccessTokenIssuer(ctx)` | Builds an `AccessTokenIssuer` (unmemoized) |
+| `refuseTokenAuth(req, what)` | Throws `AuthForbidden(what)` when `req.auth.type` is an access token |
+| `tokenHashHelper.hashAccessToken(token)` | SHA-256 hex — the stored form |
+| `tokenHashHelper.mintAccessToken(prefix)` | `MintedToken` `{ token, hash, display }` |
+| `createTokenHashHelper()` | Builds a `TokenHashHelper` |
+| `issueAccessToken(ctx, subject, request)`, `hashAccessToken(token)` | Deprecated wrappers |
+| `SERVER_AUTH_TOKEN` | `'server-auth-token'` — module alias for error locations |
+
+### Types
+
+| Symbol | Purpose |
+|---|---|
+| `AuthTokenGuardOptions` | `prefix?`, `denyAliases?`, `touchInterval?` (default 5 min), `resourceAlias?`, `profileAlias?`, `resources?` |
+| `AuthTokenConfig` | `ServerConfig` with `authToken?: { prefix? }` |
+| `AuthTokenContext` | `ServerContext<AuthTokenConfig>` |
+| `AccessTokenResource` | `MongoResource<AccessTokenRecord>` |
+| `IssueAccessTokenSubject` | `{ entityId, userId, profileId, role, scopes }` |
+| `IssueAccessTokenRequest` | `CreateAccessToken` (`name`, `scopes?`, `expiresIn?`) plus `audience?` |
+| `AccessTokenIssuer`, `RevokeAccessTokenOptions`, `MintedToken`, `TokenHashHelper` | Supporting types |
+
+## Guard behaviour
+
+A presented token is refused when it is unknown, revoked, expired, outside the configured
+`resources`, or when its identity profile is missing, unreadable or expired. On success the payload
+carries the token's **display** form (never the secret), the profile's `role`, the intersected
+scopes, and an `entitySlug` resolved through `ENTITY_RESOLVER` when one is registered. `lastUsedAt`
+is written fire-and-forget at most once per `touchInterval`. Refusals are logged once a minute per
+token and reason, with the record id only.
+
+## Common pitfalls
+
+- Passing `prefix` only to a guard you build with `makeAuthTokenGuard` — the minting handler reads the
+  prefix from config, so the two disagree and every new token is a 401. Use `appendAuthTokenGuard`.
+- Registering the token store on a different `dbAlias` than the identity resources.
+- Forgetting the deny list — a coguard-admitted token then reaches routes that must stay
+  session-only (minting, checkout, starting an OAuth flow). A child route cannot drop an inherited
+  guard; the refusal belongs in `denyAliases`.
+- Expecting a requested scope the caller lacks to be dropped — it is refused with
+  `AuthForbidden('scope')`.
+- Treating `lastUsedAt` as an access log — it is throttled and best-effort.
+- Decorating protocols with `withAuthTokenCoguard` after bindings were created.
+
+The `server-auth-token` skill covers the guard, the store and the deny-list rule in depth; the
+`auth-token` skill covers the format and routes.
+
+## Related packages
+
+- [`@owlmeans/auth-token`](../auth-token) — token format, routes, record types, constants
+- [`@owlmeans/web-auth-token`](../web-auth-token) — the browser token management panel
+- [`@owlmeans/server-oauth`](../server-oauth) — OAuth authorization server that mints audience-scoped tokens
+- [`@owlmeans/server-auth-identity`](../server-auth-identity) — the identity profiles a token is bound to
+- [`@owlmeans/mongo-resource`](../mongo-resource) — the token store's backend
+- [`@owlmeans/server-api`](../server-api) — the `handlers()` builder the handlers use
+
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
 
@@ -6,7 +182,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.51
+npx @owlmeans/agent-skills@^0.1.18-rc.52
 ```
 
 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,
   "package": "@owlmeans/server-auth-token",
-  "version": "0.1.18-rc.33",
-  "generatedAt": "2026-10-06T11:45:57.687Z",
+  "version": "0.1.18-rc.34",
+  "generatedAt": "2026-10-08T21:27:54.322Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/server-auth-token
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-auth-token": "^0.1.18-rc.33"` in `dependencies`
+**Install:** `"@owlmeans/server-auth-token": "^0.1.18-rc.34"` in `dependencies`
 **Contracts:** `@owlmeans/auth-token` — the record, the routes, the format helpers
 
 ## Key Exports
@@ -22,10 +22,10 @@ user-invocable: false
 | `prefixOf(context, opts?)` | The deployment's prefix: guard options → config → default |
 | `tokenHashHelper` — `.hashAccessToken(token)` · `.mintAccessToken(prefix)` | The stored form; one minted `{ token, hash, display }` |
 | `withAuthTokenCoguard(protocolTree, guard?)` | Return the same-shaped immutable tree with the guard appended to every already-guarded protocol |
-| `listAccessTokens` · `createAccessToken` · `revokeAccessToken` | The three handlers |
+| `listAccessTokens(protocol)` · `createAccessToken(protocol)` · `revokeAccessToken(protocol, { allowAccessTokens? })` | The three handlers; only revoke takes an option (`RevokeAccessTokenOptions`) |
 | `accessTokenIssuerOf(ctx).issueAccessToken(subject, request)` | Mint one token for `{ entityId, userId, profileId, role, scopes }` — what `createAccessToken` does over an HTTP body, and what an OAuth token endpoint calls over a session it verified itself. `request` is `CreateAccessToken` plus `audience?: string[]` |
 | `refuseTokenAuth(req, what)` | The one "interactive session only" check — throws `AuthForbidden` when `req.auth.type` is an access token |
-| `AuthTokenGuardOptions` (`prefix`, `denyAliases`, `touchInterval`, `resourceAlias`, `profileAlias`, `resources`) · `IssueAccessTokenSubject` · `IssueAccessTokenRequest` · `AuthTokenConfig` · `AccessTokenResource` | Types |
+| `AuthTokenGuardOptions` (`prefix`, `denyAliases`, `touchInterval`, `resourceAlias`, `profileAlias`, `resources`) · `IssueAccessTokenSubject` · `IssueAccessTokenRequest` · `RevokeAccessTokenOptions` · `AuthTokenConfig` · `AccessTokenResource` | Types |
 
 ## Wiring
 
@@ -94,14 +94,24 @@ timestamp is never a reason to fail a request, and awaiting it would put a datab
 critical path of every authenticated call. It answers one question — "is this token still in use?" —
 and is not an access log.
 
-## A token may never mint or revoke a token
+## A token may never mint a token; it revokes one only where the deployment opts in
 
 Minting is the one operation that turns a stolen credential into a permanent one: a token that can
-create tokens survives the revocation of the token that leaked. `createAccessToken`, `revokeAccessToken` and any other minting path (an OAuth consent approval calls
-`refuseTokenAuth` before it snapshots the subject) refuse a request whose `auth.type` is `AuthroizationType.AuthToken`, and a
+create tokens survives the revocation of the token that leaked. `createAccessToken` and any other
+minting path (an OAuth consent approval calls `refuseTokenAuth` before it snapshots the subject)
+refuse a request whose `auth.type` is `AuthroizationType.AuthToken` — always, with no option — and a
 deployment additionally names those routes in the guard's **deny list**, so the refusal is a 401 at
 the boundary rather than a check every future handler has to remember.
 
+`revokeAccessToken(protocol)` refuses a token the same way by default. `revokeAccessToken(protocol,
+{ allowAccessTokens: true })` admits one — for a deployment's coding-agent surface that lets a person
+clean up their own tokens (Viable's connector binds it on `connect.account.tokens.revoke`, while the
+browser's own `/tokens/:id` route stays session-only and on the deny list). The option widens the
+CREDENTIAL only: the token revoked must still be the caller's own profile in its own organization
+(`makeEntityScope(req).requireEntityKey()`), a foreign or unknown id still answers `AuthForbidden`
+alike, and a token may revoke itself. Revoking never creates a credential, so it cannot make a
+stolen token permanent; at worst it signs the person's other agents out.
+
 Minting only ever narrows: asking for a scope the caller does not hold is **refused**, not silently
 dropped — a token that quietly grants less than it was asked for fails later, somewhere else, with
 an error about the wrong thing. Revoke is idempotent (a retry looks like a second revoke), and
@@ -133,7 +143,7 @@ works.
 ## Tests
 
 `bun test ./tests` in the package — what the guard claims, what it resolves (including that a token
-can never outrank its profile), the mint/list/revoke rules, `accessTokenIssuerOf(ctx).issueAccessToken` parity with the route, audience admission, and the coguard's four properties.
+can never outrank its profile), the mint/list/revoke rules (the revoke option: own profile and organization only, minting still refused), `accessTokenIssuerOf(ctx).issueAccessToken` parity with the route, audience admission, and the coguard's four properties.
 
 ## Depends On
 

package/build/handlers/index.d.ts

@@ -6,7 +6,7 @@ export * from './issue.js';
 export * from './list.js';
 export * from './create.js';
 export * from './revoke.js';
-export type { IssueAccessTokenRequest, IssueAccessTokenSubject } from './types.js';
+export type { IssueAccessTokenRequest, IssueAccessTokenSubject, RevokeAccessTokenOptions } from './types.js';
 /** @deprecated compat:factory-refactor — use `accessTokenIssuerOf(ctx).issueAccessToken(…)` */
 export declare const issueAccessToken: (ctx: AuthTokenContext, subject: IssueAccessTokenSubject, payload: IssueAccessTokenRequest) => Promise<IssuedAccessToken>;
 //# sourceMappingURL=index.d.ts.map

package/build/handlers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAElF,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAE3B,YAAY,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAElF,+FAA+F;AAC/F,eAAO,MAAM,gBAAgB,QACtB,gBAAgB,WAAW,uBAAuB,WAAW,uBAAuB,KACxF,OAAO,CAAC,iBAAiB,CAAsE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAElF,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAE3B,YAAY,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAE5G,+FAA+F;AAC/F,eAAO,MAAM,gBAAgB,QACtB,gBAAgB,WAAW,uBAAuB,WAAW,uBAAuB,KACxF,OAAO,CAAC,iBAAiB,CAAsE,CAAA"}

package/build/handlers/revoke.d.ts

@@ -1,5 +1,15 @@
 import type { AuthTokenEntrypoints } from '@owlmeans/auth-token';
-export declare const revokeAccessToken: (protocol: AuthTokenEntrypoints['revoke']) => import("@owlmeans/server-entrypoint").BoundEntrypointHandler<import("@owlmeans/entrypoint").EntrypointProtocol<{
+import type { RevokeAccessTokenOptions } from './types.js';
+/**
+ * Revoke one of the caller's own tokens.
+ *
+ * By default only a credential a person produced in a browser may revoke. `allowAccessTokens`
+ * admits an access token too — a deployment's coding-agent surface that lets the person clean up
+ * their own tokens — and changes nothing else: still the caller's OWN profile in their OWN
+ * organization, and a foreign token still answers exactly as an unknown id does. Revoking never
+ * mints, so it cannot turn a stolen token into a lasting one; minting stays refused regardless.
+ */
+export declare const revokeAccessToken: (protocol: AuthTokenEntrypoints['revoke'], opts?: RevokeAccessTokenOptions) => import("@owlmeans/server-entrypoint").BoundEntrypointHandler<import("@owlmeans/entrypoint").EntrypointProtocol<{
     params: import("@owlmeans/auth-token").AccessTokenParams;
 }, {
     id: string;

package/build/handlers/revoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"revoke.d.ts","sourceRoot":"","sources":["../../src/handlers/revoke.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAOhE,eAAO,MAAM,iBAAiB,aAAc,oBAAoB,CAAC,QAAQ,CAAC;;;;GAqBxE,CAAA"}
+{"version":3,"file":"revoke.d.ts","sourceRoot":"","sources":["../../src/handlers/revoke.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAKhE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAG1D;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,aAClB,oBAAoB,CAAC,QAAQ,CAAC,SAAQ,wBAAwB;;;;GAsBxE,CAAA"}

package/build/handlers/revoke.js

@@ -3,9 +3,19 @@ import { makeEntityScope } from '@owlmeans/auth-common';
 import { handlers } from '@owlmeans/server-api';
 import { refuseTokenAuth } from './refuse.js';
 import { tokenRecordUtils } from './utils.js';
-export const revokeAccessToken = (protocol) => handlers().params(protocol, async (payload, context, req) => {
+/**
+ * Revoke one of the caller's own tokens.
+ *
+ * By default only a credential a person produced in a browser may revoke. `allowAccessTokens`
+ * admits an access token too — a deployment's coding-agent surface that lets the person clean up
+ * their own tokens — and changes nothing else: still the caller's OWN profile in their OWN
+ * organization, and a foreign token still answers exactly as an unknown id does. Revoking never
+ * mints, so it cannot turn a stolen token into a lasting one; minting stays refused regardless.
+ */
+export const revokeAccessToken = (protocol, opts = {}) => handlers().params(protocol, async (payload, context, req) => {
     const ctx = context;
-    refuseTokenAuth(req, 'token-revoke');
+    if (opts.allowAccessTokens !== true)
+        refuseTokenAuth(req, 'token-revoke');
     const entityId = makeEntityScope(req).requireEntityKey();
     const profileId = req.auth?.profileId;
     if (profileId == null)

package/build/handlers/revoke.js.map

@@ -1 +1 @@
-{"version":3,"file":"revoke.js","sourceRoot":"","sources":["../../src/handlers/revoke.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,QAAwC,EAAE,EAAE,CAAC,QAAQ,EAAoB,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE;IAC3J,MAAM,GAAG,GAAG,OAA2B,CAAA;IACvC,eAAe,CAAC,GAAG,EAAE,cAAc,CAAC,CAAA;IAEpC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,gBAAgB,EAAE,CAAA;IACxD,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,EAAE,SAAS,CAAA;IACrC,IAAI,SAAS,IAAI,IAAI;QAAE,MAAM,IAAI,aAAa,CAAC,SAAS,CAAC,CAAA;IAEzD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAClE,6FAA6F;IAC7F,8DAA8D;IAC9D,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrF,MAAM,IAAI,aAAa,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED,yDAAyD;IACzD,IAAI,MAAM,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAA;IACtG,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAA;AAC3B,CAAC,CAAC,CAAA"}
+{"version":3,"file":"revoke.js","sourceRoot":"","sources":["../../src/handlers/revoke.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE7C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,QAAwC,EAAE,IAAI,GAA6B,EAAE,EAC7E,EAAE,CAAC,QAAQ,EAAoB,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE;IACjF,MAAM,GAAG,GAAG,OAA2B,CAAA;IACvC,IAAI,IAAI,CAAC,iBAAiB,KAAK,IAAI;QAAE,eAAe,CAAC,GAAG,EAAE,cAAc,CAAC,CAAA;IAEzE,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,gBAAgB,EAAE,CAAA;IACxD,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,EAAE,SAAS,CAAA;IACrC,IAAI,SAAS,IAAI,IAAI;QAAE,MAAM,IAAI,aAAa,CAAC,SAAS,CAAC,CAAA;IAEzD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAClE,6FAA6F;IAC7F,8DAA8D;IAC9D,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrF,MAAM,IAAI,aAAa,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED,yDAAyD;IACzD,IAAI,MAAM,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAA;IACtG,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAA;AAC3B,CAAC,CAAC,CAAA"}

package/build/handlers/types.d.ts

@@ -26,4 +26,12 @@ export interface AccessTokenIssuer {
      */
     issueAccessToken: (subject: IssueAccessTokenSubject, payload: IssueAccessTokenRequest) => Promise<IssuedAccessToken>;
 }
+/** How a deployment binds `revokeAccessToken`. */
+export interface RevokeAccessTokenOptions {
+    /**
+     * Let an access token revoke one of its own person's tokens (itself included). Defaults to
+     * `false`: only an interactive session revokes. Ownership is checked the same either way.
+     */
+    allowAccessTokens?: boolean;
+}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/handlers/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAEhF,0FAA0F;AAC1F,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,QAAQ,CAAA;IACd,iFAAiF;IACjF,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,gGAAgG;AAChG,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,gBAAgB,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,uBAAuB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACrH"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/handlers/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAEhF,0FAA0F;AAC1F,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,QAAQ,CAAA;IACd,iFAAiF;IACjF,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,gGAAgG;AAChG,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,gBAAgB,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,uBAAuB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACrH;AAED,kDAAkD;AAClD,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-auth-token",
-  "version": "0.1.18-rc.33",
+  "version": "0.1.18-rc.34",
   "license": "MIT",
   "description": "The server half of OwlMeans access tokens — the store, the guard that verifies a presented token, the management handlers and the coguard that admits one on an existing route.",
   "type": "module",
@@ -24,17 +24,17 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.4.0",
-    "@owlmeans/auth": "^0.1.18-rc.40",
-    "@owlmeans/auth-common": "^0.1.18-rc.48",
-    "@owlmeans/auth-token": "^0.1.18-rc.32",
+    "@owlmeans/auth": "^0.1.18-rc.41",
+    "@owlmeans/auth-common": "^0.1.18-rc.49",
+    "@owlmeans/auth-token": "^0.1.18-rc.33",
     "@owlmeans/context": "^0.1.18-rc.34",
     "@owlmeans/entrypoint": "^0.1.18-rc.41",
-    "@owlmeans/log": "^0.1.18-rc.2",
-    "@owlmeans/mongo-resource": "^0.1.18-rc.43",
+    "@owlmeans/log": "^0.1.18-rc.3",
+    "@owlmeans/mongo-resource": "^0.1.18-rc.44",
     "@owlmeans/resource": "^0.1.18-rc.40",
-    "@owlmeans/server-api": "^0.1.18-rc.52",
-    "@owlmeans/server-auth-identity": "^0.1.18-rc.48",
-    "@owlmeans/server-context": "^0.1.18-rc.43",
+    "@owlmeans/server-api": "^0.1.18-rc.53",
+    "@owlmeans/server-auth-identity": "^0.1.18-rc.49",
+    "@owlmeans/server-context": "^0.1.18-rc.44",
     "@scure/base": "^2.4.0"
   },
   "devDependencies": {

package/src/handlers/index.ts

@@ -9,7 +9,7 @@ export * from './list.js'
 export * from './create.js'
 export * from './revoke.js'
 
-export type { IssueAccessTokenRequest, IssueAccessTokenSubject } from './types.js'
+export type { IssueAccessTokenRequest, IssueAccessTokenSubject, RevokeAccessTokenOptions } from './types.js'
 
 /** @deprecated compat:factory-refactor — use `accessTokenIssuerOf(ctx).issueAccessToken(…)` */
 export const issueAccessToken = async (

package/src/handlers/revoke.ts

@@ -4,11 +4,23 @@ import { makeEntityScope } from '@owlmeans/auth-common'
 import { handlers } from '@owlmeans/server-api'
 import type { AuthTokenContext } from '../types.js'
 import { refuseTokenAuth } from './refuse.js'
+import type { RevokeAccessTokenOptions } from './types.js'
 import { tokenRecordUtils } from './utils.js'
 
-export const revokeAccessToken = (protocol: AuthTokenEntrypoints['revoke']) => handlers<AuthTokenContext>().params(protocol, async (payload, context, req) => {
+/**
+ * Revoke one of the caller's own tokens.
+ *
+ * By default only a credential a person produced in a browser may revoke. `allowAccessTokens`
+ * admits an access token too — a deployment's coding-agent surface that lets the person clean up
+ * their own tokens — and changes nothing else: still the caller's OWN profile in their OWN
+ * organization, and a foreign token still answers exactly as an unknown id does. Revoking never
+ * mints, so it cannot turn a stolen token into a lasting one; minting stays refused regardless.
+ */
+export const revokeAccessToken = (
+  protocol: AuthTokenEntrypoints['revoke'], opts: RevokeAccessTokenOptions = {},
+) => handlers<AuthTokenContext>().params(protocol, async (payload, context, req) => {
   const ctx = context as AuthTokenContext
-  refuseTokenAuth(req, 'token-revoke')
+  if (opts.allowAccessTokens !== true) refuseTokenAuth(req, 'token-revoke')
 
   const entityId = makeEntityScope(req).requireEntityKey()
   const profileId = req.auth?.profileId

package/src/handlers/types.ts

@@ -29,3 +29,12 @@ export interface AccessTokenIssuer {
    */
   issueAccessToken: (subject: IssueAccessTokenSubject, payload: IssueAccessTokenRequest) => Promise<IssuedAccessToken>
 }
+
+/** How a deployment binds `revokeAccessToken`. */
+export interface RevokeAccessTokenOptions {
+  /**
+   * Let an access token revoke one of its own person's tokens (itself included). Defaults to
+   * `false`: only an interactive session revokes. Ownership is checked the same either way.
+   */
+  allowAccessTokens?: boolean
+}

package/tests/handlers.spec.ts

@@ -27,6 +27,7 @@ const protocols = makeAuthTokenEntrypoints()
 const listAccessTokens = bindListAccessTokens(protocols.list)
 const createAccessToken = bindCreateAccessToken(protocols.create)
 const revokeAccessToken = bindRevokeAccessToken(protocols.revoke)
+const revokeByToken = bindRevokeAccessToken(protocols.revoke, { allowAccessTokens: true })
 
 const session = (patch: Record<string, unknown> = {}): any => ({
   headers: {}, params: {}, query: {}, body: {},
@@ -184,4 +185,26 @@ describe('@owlmeans/server-auth-token — listing and revoking', () => {
       { ...session({ type: AuthroizationType.AuthToken }), params: { id: 'one' } }
     )).rejects.toThrow()
   })
+
+  test('allowAccessTokens lets a token revoke its own person\'s token — and nothing more', async () => {
+    const context = await makeTestContext()
+    await seedProfile(context)
+    await seedToken(context, tokenHashHelper.hashAccessToken('tst_one'), { id: 'one' })
+    await seedToken(context, tokenHashHelper.hashAccessToken('tst_other'), { id: 'other', profileId: 'someone-else' })
+    await seedToken(context, tokenHashHelper.hashAccessToken('tst_elsewhere'), { id: 'elsewhere', entityId: 'entity-2' })
+    const byToken = session({ type: AuthroizationType.AuthToken })
+
+    expect(await invoke(revokeByToken, context, { ...byToken, params: { id: 'one' } })).toEqual({ id: 'one' })
+    expect((await context.resource<any>(AUTH_TOKEN_RESOURCE).load('one')).revokedAt).toBeDefined()
+
+    // Another person's token, another organization's, and an unknown id answer alike — untouched.
+    for (const id of ['other', 'elsewhere', 'nonexistent']) {
+      await expect(invoke(revokeByToken, context, { ...byToken, params: { id } })).rejects.toThrow()
+    }
+    expect((await context.resource<any>(AUTH_TOKEN_RESOURCE).load('other')).revokedAt).toBeUndefined()
+    expect((await context.resource<any>(AUTH_TOKEN_RESOURCE).load('elsewhere')).revokedAt).toBeUndefined()
+
+    // The option widens only the credential: minting is refused to a token exactly as before.
+    await expect(invoke(createAccessToken, context, { ...byToken, body: { name: 'minted' } })).rejects.toThrow()
+  })
 })