@owlmeans/auth-token 0.1.18-rc.1

package/README.md

@@ -0,0 +1,15 @@
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.13
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/auth-token",
+  "version": "0.1.18-rc.1",
+  "generatedAt": "2026-09-10T18:54:42.500Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "auth-token",
+      "category": "package-specific",
+      "file": "skills/auth-token/SKILL.md",
+      "canonicalPath": ".agents/skills/auth-token/SKILL.md"
+    }
+  ]
+}

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

@@ -0,0 +1,98 @@
+---
+name: auth-token
+description: How to use @owlmeans/auth-token — the contracts behind long-lived access tokens (API keys) — the token format and its deployment prefix, the three management routes, the Authorization parsing that Bearer needs, and the client-side carrier guard a CLI or an MCP server authenticates with. Auto-invoked when importing the token entrypoints, the carrier guard, parseAuthorizationHeader, or an access-token type.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/auth-token
+
+**Layer:** Auth shared
+**Install:** `"@owlmeans/auth-token": "^0.1.18-rc.1"` 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 —
+the store, the verifying guard and the handlers — is `@owlmeans/server-auth-token`; the management
+UI is `@owlmeans/web-auth-token`.
+
+## Key Exports
+
+| 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'` |
+| `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 |
+| `authToken` | `{ base, list, create, revoke }` route aliases |
+| `GUARD_AUTH_TOKEN` · `AUTH_TOKEN_RESOURCE` · `AUTH_TOKEN_COLLECTION` | `'guard:auth-token'`, `'auth-token:token'`, `'access-token'` |
+| `AUTH_TOKEN_DEFAULT_PREFIX` | `'owl_'` — a deployment overrides it |
+| `AUTH_TOKEN_SECRET_BYTES` (24) · `AUTH_TOKEN_DISPLAY_LENGTH` (8) | 192 bits of randomness; 8 characters kept for display |
+| `AUTH_TOKEN_TOUCH_INTERVAL` (5 min) · `AUTH_TOKEN_MAX_TTL` (366 d) · `AUTH_TOKEN_NAME_MAX` (64) | Tuning |
+| `AUTH_TOKEN_SCHEME` · `BEARER_SCHEME` | `'auth-token'`, `'bearer'` — lower-cased, for comparison |
+| `AccessTokenRecord`, `AccessTokenView`, `CreateAccessToken`, `IssuedAccessToken`, `AccessTokenList`, `TokenCarrierOptions`, `AuthTokenEntrypointOptions` | Types |
+
+## The prefix is what makes a token CLAIMABLE
+
+A token is `<prefix><base58(24 random bytes)>`. The prefix is per deployment (`vib_`, `acme_`), and
+the guard answers `match` only for a value that starts with it — so an access token and an Ed25519
+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.
+
+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.
+
+## Both `AUTH-TOKEN` and `Bearer` are accepted, and that is why this package parses headers itself
+
+A third-party client configured with a URL sends `Bearer` whatever the documentation says. But
+`extractAuthToken` (`@owlmeans/auth-common`) compares the prefix against `type.toUpperCase()`, so it
+matches `AUTH-TOKEN` and can **never** match `Bearer`. `parseAuthorizationHeader` is the
+replacement: it lower-cases the scheme so a caller compares once, takes the first of several headers
+a proxy folded together, keeps a value that itself contains spaces, and answers `null` for a scheme
+with no value behind it.
+
+## The carrier guard is how a process with no browser authenticates
+
+`authMiddleware` asks every guard an entrypoint declares for `authenticated(req)` and stamps the
+first non-null answer onto the header — so registering the carrier under the alias the routes
+already name (`DEFAULT_GUARD`, usually) makes an **unchanged route declaration** work from a CLI, an
+MCP server or a test.
+
+```typescript
+context.registerService(makeTokenCarrierGuard(DEFAULT_GUARD, { token, scheme: 'auth-token' }))
+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.
+
+## The management surface is deliberately not a CRUD
+
+There is no update. A token's scopes and lifetime are fixed at issuance, because a token that can be
+widened later is a grant nobody can reason about from the moment it was created.
+
+```typescript
+context.registerEntrypoints(makeAuthTokenEntrypoints({ parent: account.base, path: '/tokens' }))
+```
+
+Mount it under an account section: the ownership gate that already guards a person's own settings
+then guards the credentials that speak for them. A base with a parent inherits its guard and gate; a
+base without one carries `opts.guard`.
+
+`CreateAccessToken.expiresIn` is **seconds** (the server clamps it to `AUTH_TOKEN_MAX_TTL`), while a
+UI usually offers days — convert at the form, and omit the field entirely for "never" rather than
+sending a zero.
+
+## Depends On
+
+- `@owlmeans/auth` — `AuthRole`, the `Authorization` header name
+- `@owlmeans/context`, `@owlmeans/entrypoint`, `@owlmeans/resource`, `@owlmeans/route`
+
+## Related
+
+- [[server-auth-token]] — the store, the verifying guard, the handlers and the coguard
+- [[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

@@ -0,0 +1,16 @@
+import type { GuardService } from '@owlmeans/entrypoint';
+import type { TokenCarrierOptions } from './types.js';
+/**
+ * A client-side guard that carries one access token.
+ *
+ * `authMiddleware` asks every guard an entrypoint declares for `authenticated(req)` and stamps the
+ * first non-null answer onto the `Authorization` header — so registering this under the alias the
+ * routes already name (`DEFAULT_GUARD`, usually) makes an unchanged route declaration work for a
+ * non-browser client. There is no session, no refresh and no storage: the token is a long-lived
+ * credential the caller was handed, and this is the object that presents it.
+ *
+ * The token may be a value or a thunk, because a CLI reads it from an environment variable that a
+ * long-running process should not cache past a reconfiguration.
+ */
+export declare const makeTokenCarrierGuard: (alias: string, opts: TokenCarrierOptions) => GuardService;
+//# sourceMappingURL=carrier.d.ts.map

package/build/carrier.d.ts.map

@@ -0,0 +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"}

package/build/carrier.js

@@ -0,0 +1,31 @@
+import { createService } from '@owlmeans/context';
+import { AUTH_TOKEN_SCHEME, BEARER_SCHEME } from './consts.js';
+/**
+ * A client-side guard that carries one access token.
+ *
+ * `authMiddleware` asks every guard an entrypoint declares for `authenticated(req)` and stamps the
+ * first non-null answer onto the `Authorization` header — so registering this under the alias the
+ * routes already name (`DEFAULT_GUARD`, usually) makes an unchanged route declaration work for a
+ * non-browser client. There is no session, no refresh and no storage: the token is a long-lived
+ * credential the caller was handed, and this is the object that presents it.
+ *
+ * The token may be a value or a thunk, because a CLI reads it from an environment variable that a
+ * long-running process should not cache past a reconfiguration.
+ */
+export const makeTokenCarrierGuard = (alias, opts) => {
+    const scheme = opts.scheme === BEARER_SCHEME ? 'Bearer' : AUTH_TOKEN_SCHEME.toUpperCase();
+    const resolve = async () => {
+        const token = typeof opts.token === 'function' ? await opts.token() : opts.token;
+        return token == null || token === '' ? null : token;
+    };
+    const service = createService(alias, {
+        match: async () => await resolve() != null,
+        handle: async () => void 0,
+        authenticated: async () => {
+            const token = await resolve();
+            return token == null ? null : `${scheme} ${token}`;
+        },
+    }, service => async () => { service.initialized = true; });
+    return service;
+};
+//# sourceMappingURL=carrier.js.map

package/build/carrier.js.map

@@ -0,0 +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"}

package/build/consts.d.ts

@@ -0,0 +1,52 @@
+/** The guard alias a long-lived access token is verified by. */
+export declare const GUARD_AUTH_TOKEN = "guard:auth-token";
+/** The resource alias holding access-token records. */
+export declare const AUTH_TOKEN_RESOURCE = "auth-token:token";
+/** The collection an access-token resource is backed by, where the backend has collections. */
+export declare const AUTH_TOKEN_COLLECTION = "access-token";
+/**
+ * The default prefix every issued token carries.
+ *
+ * The prefix is what makes a token CLAIMABLE: the guard answers `match` only for a value that
+ * starts with it, so an access token and a session bearer can share the `Bearer` scheme without
+ * either guard shadowing the other. A deployment overrides it with its own — `vib_`, `acme_` — and
+ * two deployments then never mistake each other's credentials for their own.
+ */
+export declare const AUTH_TOKEN_DEFAULT_PREFIX = "owl_";
+/** Random bytes behind one token. 24 bytes ≈ 192 bits, base58-encoded to 33 characters. */
+export declare const AUTH_TOKEN_SECRET_BYTES = 24;
+/**
+ * How many characters of a token are kept for display.
+ *
+ * The plaintext is shown once, at creation, and never again — what a list shows is the prefix plus
+ * this many characters, which is enough for a person to tell two of their own tokens apart and far
+ * too little to use.
+ */
+export declare const AUTH_TOKEN_DISPLAY_LENGTH = 8;
+/**
+ * How often a token's `lastUsedAt` is written.
+ *
+ * Every request would mean a database write per API call for a field nobody reads in real time.
+ * Five minutes answers the only question the field exists for — "is this token still in use?" —
+ * at a thousandth of the cost.
+ */
+export declare const AUTH_TOKEN_TOUCH_INTERVAL: number;
+/** The longest lifetime a token may be issued for. */
+export declare const AUTH_TOKEN_MAX_TTL: number;
+export declare const AUTH_TOKEN_NAME_MAX = 64;
+/**
+ * The route aliases of the token-management surface.
+ *
+ * Declared here so a client and a server address the same names, and mounted under whatever parent
+ * the application chooses — an account section, a settings section, a dedicated prefix.
+ */
+export declare const authToken: Readonly<{
+    base: "auth-token:base";
+    list: "auth-token:list";
+    create: "auth-token:create";
+    revoke: "auth-token:revoke";
+}>;
+/** The `Authorization` schemes a token may arrive under, lower-cased. */
+export declare const AUTH_TOKEN_SCHEME = "auth-token";
+export declare const BEARER_SCHEME = "bearer";
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,qBAAqB,CAAA;AAElD,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,qBAAqB,CAAA;AAErD,+FAA+F;AAC/F,eAAO,MAAM,qBAAqB,iBAAiB,CAAA;AAEnD;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,SAAS,CAAA;AAE/C,2FAA2F;AAC3F,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,QAAgB,CAAA;AAEtD,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,QAA4B,CAAA;AAE3D,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;EAKpB,CAAA;AAEF,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,eAAe,CAAA;AAC7C,eAAO,MAAM,aAAa,WAAW,CAAA"}

package/build/consts.js

@@ -0,0 +1,52 @@
+/** The guard alias a long-lived access token is verified by. */
+export const GUARD_AUTH_TOKEN = 'guard:auth-token';
+/** The resource alias holding access-token records. */
+export const AUTH_TOKEN_RESOURCE = 'auth-token:token';
+/** The collection an access-token resource is backed by, where the backend has collections. */
+export const AUTH_TOKEN_COLLECTION = 'access-token';
+/**
+ * The default prefix every issued token carries.
+ *
+ * The prefix is what makes a token CLAIMABLE: the guard answers `match` only for a value that
+ * starts with it, so an access token and a session bearer can share the `Bearer` scheme without
+ * either guard shadowing the other. A deployment overrides it with its own — `vib_`, `acme_` — and
+ * two deployments then never mistake each other's credentials for their own.
+ */
+export const AUTH_TOKEN_DEFAULT_PREFIX = 'owl_';
+/** Random bytes behind one token. 24 bytes ≈ 192 bits, base58-encoded to 33 characters. */
+export const AUTH_TOKEN_SECRET_BYTES = 24;
+/**
+ * How many characters of a token are kept for display.
+ *
+ * The plaintext is shown once, at creation, and never again — what a list shows is the prefix plus
+ * this many characters, which is enough for a person to tell two of their own tokens apart and far
+ * too little to use.
+ */
+export const AUTH_TOKEN_DISPLAY_LENGTH = 8;
+/**
+ * How often a token's `lastUsedAt` is written.
+ *
+ * Every request would mean a database write per API call for a field nobody reads in real time.
+ * Five minutes answers the only question the field exists for — "is this token still in use?" —
+ * at a thousandth of the cost.
+ */
+export const AUTH_TOKEN_TOUCH_INTERVAL = 5 * 60 * 1000;
+/** The longest lifetime a token may be issued for. */
+export const AUTH_TOKEN_MAX_TTL = 366 * 24 * 60 * 60 * 1000;
+export const AUTH_TOKEN_NAME_MAX = 64;
+/**
+ * The route aliases of the token-management surface.
+ *
+ * Declared here so a client and a server address the same names, and mounted under whatever parent
+ * the application chooses — an account section, a settings section, a dedicated prefix.
+ */
+export const authToken = Object.freeze({
+    base: 'auth-token:base',
+    list: 'auth-token:list',
+    create: 'auth-token:create',
+    revoke: 'auth-token:revoke',
+});
+/** The `Authorization` schemes a token may arrive under, lower-cased. */
+export const AUTH_TOKEN_SCHEME = 'auth-token';
+export const BEARER_SCHEME = 'bearer';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAA;AAElD,uDAAuD;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAA;AAErD,+FAA+F;AAC/F,MAAM,CAAC,MAAM,qBAAqB,GAAG,cAAc,CAAA;AAEnD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAA;AAE/C,2FAA2F;AAC3F,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAA;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;AAEtD,sDAAsD;AACtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAE3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAA;AAErC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,iBAAiB;IACvB,IAAI,EAAE,iBAAiB;IACvB,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,mBAAmB;CAC5B,CAAC,CAAA;AAEF,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAA;AAC7C,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CAAA"}

package/build/entrypoints.d.ts

@@ -0,0 +1,15 @@
+import type { CommonEntrypoint } from '@owlmeans/entrypoint';
+import type { AuthTokenEntrypointOptions } from './types.js';
+/**
+ * The three routes a token surface needs, ready to be spread into an application's entrypoints.
+ *
+ * Mounted under whatever parent the application chooses — an account section usually, so the
+ * ownership gate that already protects a person's own settings protects their tokens too. A base
+ * with a parent inherits its guard and its gate; a base without one carries `opts.guard`.
+ *
+ * Deliberately not a resource CRUD: there is no update. A token's scopes and lifetime are fixed at
+ * issuance, because a token that can be widened later is a token whose grant nobody can reason
+ * about from the moment it was created.
+ */
+export declare const makeAuthTokenEntrypoints: (opts?: AuthTokenEntrypointOptions) => CommonEntrypoint[];
+//# sourceMappingURL=entrypoints.d.ts.map

package/build/entrypoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoints.d.ts","sourceRoot":"","sources":["../src/entrypoints.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAI5D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,UAC7B,0BAA0B,KAC/B,gBAAgB,EAoBlB,CAAA"}

package/build/entrypoints.js

@@ -0,0 +1,30 @@
+import { body, entrypoint, filter, guard, params } from '@owlmeans/entrypoint';
+import { route, RouteMethod } from '@owlmeans/route';
+import { authToken } from './consts.js';
+import { AccessTokenParamsSchema, CreateAccessTokenSchema } from './schemas.js';
+/**
+ * The three routes a token surface needs, ready to be spread into an application's entrypoints.
+ *
+ * Mounted under whatever parent the application chooses — an account section usually, so the
+ * ownership gate that already protects a person's own settings protects their tokens too. A base
+ * with a parent inherits its guard and its gate; a base without one carries `opts.guard`.
+ *
+ * Deliberately not a resource CRUD: there is no update. A token's scopes and lifetime are fixed at
+ * issuance, because a token that can be widened later is a token whose grant nobody can reason
+ * about from the moment it was created.
+ */
+export const makeAuthTokenEntrypoints = (opts = {}) => {
+    const path = opts.path ?? '/tokens';
+    const base = opts.parent != null
+        ? entrypoint(route(authToken.base, path, { parent: opts.parent }))
+        : entrypoint(route(authToken.base, path), opts.guard != null ? guard(opts.guard) : undefined);
+    return [
+        base,
+        entrypoint(route(authToken.list, '/', {
+            parent: authToken.base, method: RouteMethod.GET
+        })),
+        entrypoint(route(authToken.create, '/', { parent: authToken.base, method: RouteMethod.POST }), filter(body(CreateAccessTokenSchema))),
+        entrypoint(route(authToken.revoke, '/:id', { parent: authToken.base, method: RouteMethod.DELETE }), filter(params(AccessTokenParamsSchema))),
+    ];
+};
+//# sourceMappingURL=entrypoints.js.map

package/build/entrypoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoints.js","sourceRoot":"","sources":["../src/entrypoints.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAE9E,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAG/E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,IAAI,GAA+B,EAAE,EACjB,EAAE;IACtB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,SAAS,CAAA;IACnC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI;QAC9B,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAClE,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAE/F,OAAO;QACL,IAAI;QACJ,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE;YACpC,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,GAAG;SAChD,CAAC,CAAC;QACH,UAAU,CACR,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC,EAClF,MAAM,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,CACtC;QACD,UAAU,CACR,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,EACvF,MAAM,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC,CACxC;KACF,CAAA;AACH,CAAC,CAAA"}

package/build/format.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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;
+//# sourceMappingURL=format.d.ts.map

package/build/format.d.ts.map

@@ -0,0 +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"}

package/build/format.js

@@ -0,0 +1,36 @@
+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)}`;
+};
+//# sourceMappingURL=format.js.map

package/build/format.js.map

@@ -0,0 +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"}

package/build/index.d.ts

@@ -0,0 +1,7 @@
+export * from './consts.js';
+export * from './schemas.js';
+export * from './entrypoints.js';
+export * from './format.js';
+export * from './carrier.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +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"}

package/build/index.js

@@ -0,0 +1,6 @@
+export * from './consts.js';
+export * from './schemas.js';
+export * from './entrypoints.js';
+export * from './format.js';
+export * from './carrier.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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"}

package/build/schemas.d.ts

@@ -0,0 +1,5 @@
+import type { JSONSchemaType } from 'ajv';
+import type { AccessTokenParams, CreateAccessToken } from './types.js';
+export declare const CreateAccessTokenSchema: JSONSchemaType<CreateAccessToken>;
+export declare const AccessTokenParamsSchema: JSONSchemaType<AccessTokenParams>;
+//# sourceMappingURL=schemas.d.ts.map

package/build/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AAEzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEtE,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,iBAAiB,CAmBrE,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,iBAAiB,CAKrE,CAAA"}

package/build/schemas.js

@@ -0,0 +1,28 @@
+import { AUTH_TOKEN_MAX_TTL, AUTH_TOKEN_NAME_MAX } from './consts.js';
+export const CreateAccessTokenSchema = {
+    type: 'object',
+    properties: {
+        name: { type: 'string', minLength: 1, maxLength: AUTH_TOKEN_NAME_MAX },
+        scopes: {
+            type: 'array',
+            nullable: true,
+            maxItems: 32,
+            items: { type: 'string', minLength: 1, maxLength: 128 },
+        },
+        expiresIn: {
+            type: 'integer',
+            nullable: true,
+            minimum: 60,
+            maximum: Math.floor(AUTH_TOKEN_MAX_TTL / 1000),
+        },
+    },
+    required: ['name'],
+    additionalProperties: false,
+};
+export const AccessTokenParamsSchema = {
+    type: 'object',
+    properties: { id: { type: 'string', minLength: 1, maxLength: 128 } },
+    required: ['id'],
+    additionalProperties: false,
+};
+//# sourceMappingURL=schemas.js.map

package/build/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGrE,MAAM,CAAC,MAAM,uBAAuB,GAAsC;IACxE,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,mBAAmB,EAAE;QACtE,MAAM,EAAE;YACN,IAAI,EAAE,OAAO;YACb,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,EAAE;YACZ,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;SACxD;QACD,SAAS,EAAE;YACT,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,kBAAkB,GAAG,IAAI,CAAC;SAC/C;KACF;IACD,QAAQ,EAAE,CAAC,MAAM,CAAC;IAClB,oBAAoB,EAAE,KAAK;CAC5B,CAAA;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAsC;IACxE,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE;IACpE,QAAQ,EAAE,CAAC,IAAI,CAAC;IAChB,oBAAoB,EAAE,KAAK;CAC5B,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,72 @@
+import type { AuthRole } from '@owlmeans/auth';
+import type { ResourceRecord } from '@owlmeans/resource';
+/**
+ * One long-lived access token, as stored.
+ *
+ * The plaintext is never here. What is stored is its hash — a stolen database yields no usable
+ * credential — plus `display`, the prefix and a few characters, which is what a person sees in a
+ * list. A token is bound to the profile that minted it and can never outrank it: the guard
+ * intersects its scopes with the profile's on every request, so revoking a profile's access
+ * revokes every token it ever issued without touching a single token record.
+ */
+export interface AccessTokenRecord extends ResourceRecord {
+    id?: string;
+    /** SHA-256 of the plaintext, hex. The only copy of the secret that exists after issuance. */
+    hash: string;
+    /** Prefix + the first characters of the secret. Shown in lists; useless as a credential. */
+    display: string;
+    /** What the owner called it. */
+    name: string;
+    userId: string;
+    profileId: string;
+    entityId: string;
+    scopes: string[];
+    role: AuthRole;
+    createdAt: Date;
+    updatedAt?: Date;
+    /** Written at most once per touch interval — a usage signal, not an access log. */
+    lastUsedAt?: Date;
+    expiresAt?: Date;
+    /** Set once and never unset. A revoked token is kept so its display name still resolves. */
+    revokedAt?: Date;
+}
+/** What a caller may see. The hash never leaves the server. */
+export type AccessTokenView = Omit<AccessTokenRecord, 'hash'>;
+export interface CreateAccessToken {
+    name: string;
+    /** A subset of the caller's own scopes. Defaults to all of them. */
+    scopes?: string[];
+    /** Lifetime in seconds. Absent means no expiry; clamped to the maximum TTL. */
+    expiresIn?: number;
+}
+/** The one moment the plaintext exists outside the caller's own machine. */
+export interface IssuedAccessToken {
+    token: string;
+    record: AccessTokenView;
+}
+export interface AccessTokenList {
+    items: AccessTokenView[];
+}
+export interface AccessTokenParams {
+    id: string;
+}
+/**
+ * How a client presents a token it already holds.
+ *
+ * `auth-token` is the OwlMeans scheme; `bearer` is what a third-party client — an MCP host reading
+ * a URL configuration, a curl script — will send whatever the documentation says. Both are
+ * accepted on the way in; a client chooses the one its transport is comfortable with.
+ */
+export interface TokenCarrierOptions {
+    token: string | (() => string | Promise<string>);
+    scheme?: 'auth-token' | 'bearer';
+}
+export interface AuthTokenEntrypointOptions {
+    /** The entrypoint the token routes hang under. */
+    parent?: string;
+    /** 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. */
+    guard?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +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;AAExD;;;;;;;;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"}

package/build/types.js

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

package/build/types.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@owlmeans/auth-token",
+  "version": "0.1.18-rc.1",
+  "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",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 2 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/auth": "^0.1.18-rc.10",
+    "@owlmeans/context": "^0.1.18-rc.9",
+    "@owlmeans/entrypoint": "^0.1.18-rc.12",
+    "@owlmeans/resource": "^0.1.18-rc.10",
+    "@owlmeans/route": "^0.1.18-rc.10"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.4.0",
+    "ajv": "^8.17.1",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/carrier.ts

@@ -0,0 +1,40 @@
+import { createService } from '@owlmeans/context'
+import type { GuardService } from '@owlmeans/entrypoint'
+import { AUTH_TOKEN_SCHEME, BEARER_SCHEME } from './consts.js'
+import type { TokenCarrierOptions } from './types.js'
+
+/**
+ * A client-side guard that carries one access token.
+ *
+ * `authMiddleware` asks every guard an entrypoint declares for `authenticated(req)` and stamps the
+ * first non-null answer onto the `Authorization` header — so registering this under the alias the
+ * routes already name (`DEFAULT_GUARD`, usually) makes an unchanged route declaration work for a
+ * non-browser client. There is no session, no refresh and no storage: the token is a long-lived
+ * credential the caller was handed, and this is the object that presents it.
+ *
+ * The token may be a value or a thunk, because a CLI reads it from an environment variable that a
+ * long-running process should not cache past a reconfiguration.
+ */
+export const makeTokenCarrierGuard = (alias: string, opts: TokenCarrierOptions): GuardService => {
+  const scheme = opts.scheme === BEARER_SCHEME ? 'Bearer' : AUTH_TOKEN_SCHEME.toUpperCase()
+
+  const resolve = async (): Promise<string | null> => {
+    const token = typeof opts.token === 'function' ? await opts.token() : opts.token
+
+    return token == null || token === '' ? null : token
+  }
+
+  const service: GuardService = createService<GuardService>(alias, {
+    match: async () => await resolve() != null,
+
+    handle: async <T>() => void 0 as T,
+
+    authenticated: async () => {
+      const token = await resolve()
+
+      return token == null ? null : `${scheme} ${token}`
+    },
+  }, service => async () => { service.initialized = true })
+
+  return service
+}

package/src/consts.ts

@@ -0,0 +1,61 @@
+/** The guard alias a long-lived access token is verified by. */
+export const GUARD_AUTH_TOKEN = 'guard:auth-token'
+
+/** The resource alias holding access-token records. */
+export const AUTH_TOKEN_RESOURCE = 'auth-token:token'
+
+/** The collection an access-token resource is backed by, where the backend has collections. */
+export const AUTH_TOKEN_COLLECTION = 'access-token'
+
+/**
+ * The default prefix every issued token carries.
+ *
+ * The prefix is what makes a token CLAIMABLE: the guard answers `match` only for a value that
+ * starts with it, so an access token and a session bearer can share the `Bearer` scheme without
+ * either guard shadowing the other. A deployment overrides it with its own — `vib_`, `acme_` — and
+ * two deployments then never mistake each other's credentials for their own.
+ */
+export const AUTH_TOKEN_DEFAULT_PREFIX = 'owl_'
+
+/** Random bytes behind one token. 24 bytes ≈ 192 bits, base58-encoded to 33 characters. */
+export const AUTH_TOKEN_SECRET_BYTES = 24
+
+/**
+ * How many characters of a token are kept for display.
+ *
+ * The plaintext is shown once, at creation, and never again — what a list shows is the prefix plus
+ * this many characters, which is enough for a person to tell two of their own tokens apart and far
+ * too little to use.
+ */
+export const AUTH_TOKEN_DISPLAY_LENGTH = 8
+
+/**
+ * How often a token's `lastUsedAt` is written.
+ *
+ * Every request would mean a database write per API call for a field nobody reads in real time.
+ * Five minutes answers the only question the field exists for — "is this token still in use?" —
+ * at a thousandth of the cost.
+ */
+export const AUTH_TOKEN_TOUCH_INTERVAL = 5 * 60 * 1000
+
+/** The longest lifetime a token may be issued for. */
+export const AUTH_TOKEN_MAX_TTL = 366 * 24 * 60 * 60 * 1000
+
+export const AUTH_TOKEN_NAME_MAX = 64
+
+/**
+ * The route aliases of the token-management surface.
+ *
+ * Declared here so a client and a server address the same names, and mounted under whatever parent
+ * the application chooses — an account section, a settings section, a dedicated prefix.
+ */
+export const authToken = Object.freeze({
+  base: 'auth-token:base',
+  list: 'auth-token:list',
+  create: 'auth-token:create',
+  revoke: 'auth-token:revoke',
+})
+
+/** The `Authorization` schemes a token may arrive under, lower-cased. */
+export const AUTH_TOKEN_SCHEME = 'auth-token'
+export const BEARER_SCHEME = 'bearer'

package/src/entrypoints.ts

@@ -0,0 +1,41 @@
+import { body, entrypoint, filter, guard, params } from '@owlmeans/entrypoint'
+import type { CommonEntrypoint } from '@owlmeans/entrypoint'
+import { route, RouteMethod } from '@owlmeans/route'
+import { authToken } from './consts.js'
+import { AccessTokenParamsSchema, CreateAccessTokenSchema } from './schemas.js'
+import type { AuthTokenEntrypointOptions } from './types.js'
+
+/**
+ * The three routes a token surface needs, ready to be spread into an application's entrypoints.
+ *
+ * Mounted under whatever parent the application chooses — an account section usually, so the
+ * ownership gate that already protects a person's own settings protects their tokens too. A base
+ * with a parent inherits its guard and its gate; a base without one carries `opts.guard`.
+ *
+ * Deliberately not a resource CRUD: there is no update. A token's scopes and lifetime are fixed at
+ * issuance, because a token that can be widened later is a token whose grant nobody can reason
+ * about from the moment it was created.
+ */
+export const makeAuthTokenEntrypoints = (
+  opts: AuthTokenEntrypointOptions = {}
+): CommonEntrypoint[] => {
+  const path = opts.path ?? '/tokens'
+  const base = opts.parent != null
+    ? entrypoint(route(authToken.base, path, { parent: opts.parent }))
+    : entrypoint(route(authToken.base, path), opts.guard != null ? guard(opts.guard) : undefined)
+
+  return [
+    base,
+    entrypoint(route(authToken.list, '/', {
+      parent: authToken.base, method: RouteMethod.GET
+    })),
+    entrypoint(
+      route(authToken.create, '/', { parent: authToken.base, method: RouteMethod.POST }),
+      filter(body(CreateAccessTokenSchema))
+    ),
+    entrypoint(
+      route(authToken.revoke, '/:id', { parent: authToken.base, method: RouteMethod.DELETE }),
+      filter(params(AccessTokenParamsSchema))
+    ),
+  ]
+}

package/src/format.ts

@@ -0,0 +1,42 @@
+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: 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 }
+}
+
+/** 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)
+
+/**
+ * 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
+
+  return `${prefix}${secret.slice(0, AUTH_TOKEN_DISPLAY_LENGTH)}`
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './consts.js'
+export * from './schemas.js'
+export * from './entrypoints.js'
+export * from './format.js'
+export * from './carrier.js'
+export type * from './types.js'

package/src/schemas.ts

@@ -0,0 +1,31 @@
+import type { JSONSchemaType } from 'ajv'
+import { AUTH_TOKEN_MAX_TTL, AUTH_TOKEN_NAME_MAX } from './consts.js'
+import type { AccessTokenParams, CreateAccessToken } from './types.js'
+
+export const CreateAccessTokenSchema: JSONSchemaType<CreateAccessToken> = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', minLength: 1, maxLength: AUTH_TOKEN_NAME_MAX },
+    scopes: {
+      type: 'array',
+      nullable: true,
+      maxItems: 32,
+      items: { type: 'string', minLength: 1, maxLength: 128 },
+    },
+    expiresIn: {
+      type: 'integer',
+      nullable: true,
+      minimum: 60,
+      maximum: Math.floor(AUTH_TOKEN_MAX_TTL / 1000),
+    },
+  },
+  required: ['name'],
+  additionalProperties: false,
+}
+
+export const AccessTokenParamsSchema: JSONSchemaType<AccessTokenParams> = {
+  type: 'object',
+  properties: { id: { type: 'string', minLength: 1, maxLength: 128 } },
+  required: ['id'],
+  additionalProperties: false,
+}

package/src/types.ts

@@ -0,0 +1,79 @@
+import type { AuthRole } from '@owlmeans/auth'
+import type { ResourceRecord } from '@owlmeans/resource'
+
+/**
+ * One long-lived access token, as stored.
+ *
+ * The plaintext is never here. What is stored is its hash — a stolen database yields no usable
+ * credential — plus `display`, the prefix and a few characters, which is what a person sees in a
+ * list. A token is bound to the profile that minted it and can never outrank it: the guard
+ * intersects its scopes with the profile's on every request, so revoking a profile's access
+ * revokes every token it ever issued without touching a single token record.
+ */
+export interface AccessTokenRecord extends ResourceRecord {
+  id?: string
+  /** SHA-256 of the plaintext, hex. The only copy of the secret that exists after issuance. */
+  hash: string
+  /** Prefix + the first characters of the secret. Shown in lists; useless as a credential. */
+  display: string
+  /** What the owner called it. */
+  name: string
+  userId: string
+  profileId: string
+  entityId: string
+  scopes: string[]
+  role: AuthRole
+  createdAt: Date
+  updatedAt?: Date
+  /** Written at most once per touch interval — a usage signal, not an access log. */
+  lastUsedAt?: Date
+  expiresAt?: Date
+  /** Set once and never unset. A revoked token is kept so its display name still resolves. */
+  revokedAt?: Date
+}
+
+/** What a caller may see. The hash never leaves the server. */
+export type AccessTokenView = Omit<AccessTokenRecord, 'hash'>
+
+export interface CreateAccessToken {
+  name: string
+  /** A subset of the caller's own scopes. Defaults to all of them. */
+  scopes?: string[]
+  /** Lifetime in seconds. Absent means no expiry; clamped to the maximum TTL. */
+  expiresIn?: number
+}
+
+/** The one moment the plaintext exists outside the caller's own machine. */
+export interface IssuedAccessToken {
+  token: string
+  record: AccessTokenView
+}
+
+export interface AccessTokenList {
+  items: AccessTokenView[]
+}
+
+export interface AccessTokenParams {
+  id: string
+}
+
+/**
+ * How a client presents a token it already holds.
+ *
+ * `auth-token` is the OwlMeans scheme; `bearer` is what a third-party client — an MCP host reading
+ * a URL configuration, a curl script — will send whatever the documentation says. Both are
+ * accepted on the way in; a client chooses the one its transport is comfortable with.
+ */
+export interface TokenCarrierOptions {
+  token: string | (() => string | Promise<string>)
+  scheme?: 'auth-token' | 'bearer'
+}
+
+export interface AuthTokenEntrypointOptions {
+  /** The entrypoint the token routes hang under. */
+  parent?: string
+  /** 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. */
+  guard?: string
+}

package/tests/carrier.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from 'bun:test'
+import { AppType, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import type { GuardService } from '@owlmeans/entrypoint'
+import { makeTokenCarrierGuard } from '../src/carrier.js'
+
+const contextWith = async (guard: GuardService): Promise<BasicContext<BasicConfig>> => {
+  const cfg: BasicConfig = { ready: false, service: 'carrier-tests', type: AppType.Backend, services: {} }
+  const context = makeBasicContext(cfg) as BasicContext<BasicConfig>
+  context.registerService(guard)
+  context.configure()
+  await context.init()
+
+  return context
+}
+
+describe('@owlmeans/auth-token — the client carrier guard', () => {
+  test('presents the OwlMeans scheme by default', async () => {
+    const guard = makeTokenCarrierGuard('carrier', { token: 'owl_secret' })
+    await contextWith(guard)
+
+    expect(await guard.authenticated()).toBe('AUTH-TOKEN owl_secret')
+  })
+
+  test('presents Bearer when asked — what a URL-configured client sends', async () => {
+    const guard = makeTokenCarrierGuard('carrier', { token: 'owl_secret', scheme: 'bearer' })
+    await contextWith(guard)
+
+    expect(await guard.authenticated()).toBe('Bearer owl_secret')
+  })
+
+  test('resolves a thunk on every call, so a reconfigured token is picked up', async () => {
+    let current = 'owl_first'
+    const guard = makeTokenCarrierGuard('carrier', { token: () => current })
+    await contextWith(guard)
+
+    expect(await guard.authenticated()).toBe('AUTH-TOKEN owl_first')
+    current = 'owl_second'
+    expect(await guard.authenticated()).toBe('AUTH-TOKEN owl_second')
+  })
+
+  test('holds no credential when the token is empty, and matches nothing', async () => {
+    const guard = makeTokenCarrierGuard('carrier', { token: '' })
+    await contextWith(guard)
+
+    expect(await guard.authenticated()).toBeNull()
+    expect(await guard.match({} as any, {} as any)).toBe(false)
+  })
+})

package/tests/format.spec.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from 'bun:test'
+import { displayOf, isAccessToken, parseAuthorizationHeader } 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')
+  })
+
+  test('takes the first header when a proxy folded several', () => {
+    expect(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()
+  })
+
+  test('keeps a value that itself contains spaces', () => {
+    expect(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)
+    // 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)
+  })
+
+  test('the display form keeps the prefix and eight characters of the secret', () => {
+    const display = 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)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["@owlmeans/dep-config/tsconfig.base.json"],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}