@owlmeans/auth-token 0.1.18-rc.31 → 0.1.18-rc.33

package/README.md

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

package/build/format/types.d.ts

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

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

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

package/build/format/types.js

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

package/build/format/types.js.map

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

package/build/format.d.ts

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

package/build/format.d.ts.map

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

package/build/format.js

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

package/build/format.js.map

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

package/build/index.d.ts

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

package/build/index.d.ts.map

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

package/build/types.d.ts

@@ -45,7 +45,8 @@ export interface AccessTokenRecord extends ResourceRecord {
     audience?: string[];
 }
 /** What a caller may see. The hash never leaves the server. */
-export type AccessTokenView = Omit<AccessTokenRecord, 'hash'>;
+export interface AccessTokenView extends Omit<AccessTokenRecord, 'hash'> {
+}
 export interface CreateAccessToken {
     name: string;
     /** A subset of the caller's own scopes. Defaults to all of them. */

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/auth-token",
-  "version": "0.1.18-rc.31",
+  "version": "0.1.18-rc.33",
   "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",
@@ -23,11 +23,11 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.39",
-    "@owlmeans/context": "^0.1.18-rc.33",
-    "@owlmeans/entrypoint": "^0.1.18-rc.40",
-    "@owlmeans/resource": "^0.1.18-rc.39",
-    "@owlmeans/route": "^0.1.18-rc.34"
+    "@owlmeans/auth": "^0.1.18-rc.41",
+    "@owlmeans/context": "^0.1.18-rc.34",
+    "@owlmeans/entrypoint": "^0.1.18-rc.41",
+    "@owlmeans/resource": "^0.1.18-rc.40",
+    "@owlmeans/route": "^0.1.18-rc.35"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/src/format/types.ts

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

package/src/format.ts

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

package/src/index.ts

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

package/src/types.ts

@@ -47,7 +47,7 @@ export interface AccessTokenRecord extends ResourceRecord {
 }
 
 /** What a caller may see. The hash never leaves the server. */
-export type AccessTokenView = Omit<AccessTokenRecord, 'hash'>
+export interface AccessTokenView extends Omit<AccessTokenRecord, 'hash'> {}
 
 export interface CreateAccessToken {
   name: string

package/tests/format.spec.ts

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