@owlmeans/server-auth-token 0.1.18-rc.1

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,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,mBAAmB,YAAY,CAAA"}

package/build/index.js

@@ -0,0 +1,8 @@
+export * from './consts.js';
+export * from './resource.js';
+export * from './guard.js';
+export * from './hash.js';
+export * from './coguard.js';
+export * from './append.js';
+export * from './handlers/index.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,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA"}

package/build/resource.d.ts

@@ -0,0 +1,14 @@
+import type { AccessTokenResource } from './types.js';
+/**
+ * Where access tokens live.
+ *
+ * `entityId` and `profileId` are stored as plain strings and only indexed — never declared as
+ * ObjectId references — because that is how the identity records they point at store them, and a
+ * reference declared on one side of a join and not the other finds nothing.
+ *
+ * No `$jsonSchema` is applied. The write path is one handler with a validated body, and a schema
+ * on the collection would have to be kept in step with a record the guard writes to on every
+ * request (`lastUsedAt`) for no protection the handler does not already give.
+ */
+export declare const makeAccessTokenResource: (dbAlias?: string) => AccessTokenResource;
+//# sourceMappingURL=resource.d.ts.map

package/build/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,aAAc,MAAM,KAAG,mBAW1D,CAAA"}

package/build/resource.js

@@ -0,0 +1,23 @@
+import { AUTH_TOKEN_COLLECTION, AUTH_TOKEN_RESOURCE } from '@owlmeans/auth-token';
+import { makeMongoResource } from '@owlmeans/mongo-resource';
+/**
+ * Where access tokens live.
+ *
+ * `entityId` and `profileId` are stored as plain strings and only indexed — never declared as
+ * ObjectId references — because that is how the identity records they point at store them, and a
+ * reference declared on one side of a join and not the other finds nothing.
+ *
+ * No `$jsonSchema` is applied. The write path is one handler with a validated body, and a schema
+ * on the collection would have to be kept in step with a record the guard writes to on every
+ * request (`lastUsedAt`) for no protection the handler does not already give.
+ */
+export const makeAccessTokenResource = (dbAlias) => {
+    const resource = makeMongoResource(AUTH_TOKEN_RESOURCE, dbAlias, undefined, AUTH_TOKEN_COLLECTION);
+    // The lookup every authenticated request makes. Unique because two records answering one
+    // presented secret would make revocation a coin toss.
+    resource.index('hash', { hash: 1 }, { unique: true });
+    resource.index('owner', { entityId: 1, profileId: 1 });
+    resource.index('expiresAt', { expiresAt: 1 }, { sparse: true });
+    return resource;
+};
+//# sourceMappingURL=resource.js.map

package/build/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAEjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAG5D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,OAAgB,EAAuB,EAAE;IAC/E,MAAM,QAAQ,GAAG,iBAAiB,CAChC,mBAAmB,EAAE,OAAO,EAAE,SAAS,EAAE,qBAAqB,CAC/D,CAAA;IACD,yFAAyF;IACzF,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IACrD,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAA;IACtD,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IAE/D,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,36 @@
+import type { AccessTokenRecord } from '@owlmeans/auth-token';
+import type { MongoResource } from '@owlmeans/mongo-resource';
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context';
+export type AccessTokenResource = MongoResource<AccessTokenRecord>;
+export interface AuthTokenGuardOptions {
+    /**
+     * The prefix every token this deployment issues carries.
+     *
+     * Also what the guard claims on: a `Bearer` value without it is left to whatever other guard
+     * the route declares.
+     */
+    prefix?: string;
+    /**
+     * Routes this guard refuses even when the entrypoint declares it.
+     *
+     * A guard added as a coguard reaches every child of the base it was added to, and a child
+     * cannot drop an inherited guard — so a route that must stay behind an interactive session
+     * (opening a checkout, starting an OAuth flow, minting another token) is named here. Refusing
+     * in `match` rather than in the handler is what makes the refusal a 401 rather than a route
+     * that quietly works.
+     */
+    denyAliases?: string[];
+    /** How often `lastUsedAt` may be written. Defaults to the package constant. */
+    touchInterval?: number;
+    /** Resource alias holding the token records. */
+    resourceAlias?: string;
+    /** Resource alias holding the identity profiles a token is bound to. */
+    profileAlias?: string;
+}
+export interface AuthTokenConfig extends ServerConfig {
+    authToken?: {
+        prefix?: string;
+    };
+}
+export type AuthTokenContext<C extends AuthTokenConfig = AuthTokenConfig> = ServerContext<C>;
+//# 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,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAE3E,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAAA;AAElE,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,SAAS,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB,CAAA;CACF;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI,aAAa,CAAC,CAAC,CAAC,CAAA"}

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,48 @@
+{
+  "name": "@owlmeans/server-auth-token",
+  "version": "0.1.18-rc.1",
+  "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",
+  "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": {
+    "@noble/hashes": "^1.5.0",
+    "@owlmeans/auth": "^0.1.18-rc.10",
+    "@owlmeans/auth-common": "^0.1.18-rc.14",
+    "@owlmeans/auth-token": "^0.1.18-rc.1",
+    "@owlmeans/context": "^0.1.18-rc.9",
+    "@owlmeans/entrypoint": "^0.1.18-rc.12",
+    "@owlmeans/mongo-resource": "^0.1.18-rc.13",
+    "@owlmeans/resource": "^0.1.18-rc.10",
+    "@owlmeans/server-api": "^0.1.18-rc.18",
+    "@owlmeans/server-auth-identity": "^0.1.18-rc.14",
+    "@owlmeans/server-context": "^0.1.18-rc.13",
+    "@scure/base": "^1.1.9"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.4.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/append.ts

@@ -0,0 +1,34 @@
+import { GUARD_AUTH_TOKEN } from '@owlmeans/auth-token'
+import type { BasicContext } from '@owlmeans/context'
+import { makeAuthTokenGuard } from './guard.js'
+import { makeAccessTokenResource } from './resource.js'
+import type { AuthTokenConfig, AuthTokenGuardOptions } from './types.js'
+
+/**
+ * Register the token store.
+ *
+ * Pass the same `dbAlias` the identity resources use: a token's `entityId`/`profileId` are read
+ * back against those collections on every request, and splitting the two across databases makes
+ * every lookup a cross-database join nobody wrote.
+ */
+export const appendAuthTokenResources = (context: BasicContext<any>, dbAlias?: string): void => {
+  context.registerResource(makeAccessTokenResource(dbAlias))
+}
+
+/**
+ * Register the guard that verifies a presented access token.
+ *
+ * A `prefix` passed here is written into the configuration, because the guard is not the only
+ * reader: the minting handler has no guard instance to ask, and the two MUST agree — a deployment
+ * that told only the guard would issue `owl_…` tokens its own guard refuses to claim, and every
+ * request would 401 with nothing anywhere saying why.
+ */
+export const appendAuthTokenGuard = (
+  context: BasicContext<any>, alias: string = GUARD_AUTH_TOKEN, opts?: AuthTokenGuardOptions
+): void => {
+  if (opts?.prefix != null) {
+    const cfg = context.cfg as AuthTokenConfig
+    cfg.authToken = { ...cfg.authToken, prefix: opts.prefix }
+  }
+  context.registerService(makeAuthTokenGuard(alias, opts))
+}

package/src/coguard.ts

@@ -0,0 +1,23 @@
+import { GUARD_AUTH_TOKEN } from '@owlmeans/auth-token'
+
+/**
+ * Let an access token authenticate every route that already has a guard.
+ *
+ * An API client drives the same surface a browser does — projects, stories, files — so admitting
+ * the token only on a dedicated prefix would mean a second copy of every route. The coguard is
+ * appended, never substituted: the primary guard stays first and still claims its own credential,
+ * and this one matches only a value carrying the deployment's token prefix.
+ *
+ * Routes that must stay behind an interactive session are named in the GUARD's deny list rather
+ * than skipped here — a child entrypoint inherits every guard its ancestors declare and cannot
+ * drop one, so the refusal has to live where the credential is inspected.
+ */
+export const setupAuthTokenCoguard = (
+  entrypoints: Array<{ guards?: string[] }>, guard: string = GUARD_AUTH_TOKEN
+): void => {
+  entrypoints.forEach(entrypoint => {
+    if (entrypoint.guards == null || entrypoint.guards.length < 1) return
+    if (entrypoint.guards.includes(guard)) return
+    entrypoint.guards = [...entrypoint.guards, guard]
+  })
+}

package/src/consts.ts

@@ -0,0 +1,2 @@
+/** Service alias of the module, for error locations. */
+export const SERVER_AUTH_TOKEN = 'server-auth-token'

package/src/guard.ts

@@ -0,0 +1,143 @@
+import type { Auth } from '@owlmeans/auth'
+import { ALL_SCOPES, AuthroizationType } from '@owlmeans/auth'
+import {
+  AUTH_TOKEN_DEFAULT_PREFIX, AUTH_TOKEN_SCHEME, AUTH_TOKEN_RESOURCE, AUTH_TOKEN_TOUCH_INTERVAL,
+  BEARER_SCHEME, GUARD_AUTH_TOKEN, isAccessToken, parseAuthorizationHeader
+} from '@owlmeans/auth-token'
+import { AUTH_HEADER } from '@owlmeans/auth'
+import { ENTITY_RESOLVER } from '@owlmeans/auth-common'
+import type { EntityResolverService } from '@owlmeans/auth-common'
+import { createService } from '@owlmeans/context'
+import type { AbstractRequest, AbstractResponse, GuardService } from '@owlmeans/entrypoint'
+import { AUTH_IDENTITY_PROFILE } from '@owlmeans/server-auth-identity'
+import type { IdentityProfile, IdentityProfileResource } from '@owlmeans/server-auth-identity'
+import { hashAccessToken } from './hash.js'
+import type { AccessTokenResource, AuthTokenConfig, AuthTokenContext, AuthTokenGuardOptions } from './types.js'
+
+/** Where the deployment's prefix comes from: the guard's own options, then config, then default. */
+export const prefixOf = (context: AuthTokenContext, opts?: AuthTokenGuardOptions): string =>
+  opts?.prefix ?? (context.cfg as AuthTokenConfig).authToken?.prefix ?? AUTH_TOKEN_DEFAULT_PREFIX
+
+/**
+ * The guard that verifies a long-lived access token.
+ *
+ * It is a GUARD, not an authentication method: nothing is exchanged, no envelope is signed, no
+ * session begins. A caller presents a credential it was handed once, and the guard turns it into
+ * the same `Auth` payload every other guard produces — so ownership gates, entitlement gates and
+ * handlers written against a browser session work unchanged for an API client.
+ *
+ * Three properties are what keep it from colliding with the guards it sits beside:
+ *
+ * - it claims a header only when the value carries the deployment's prefix, so an OwlMeans
+ *   `ED25519-BASIC-TOKEN` bearer, an OIDC one, and this one can all arrive under `Authorization`
+ *   without any of them shadowing the others;
+ * - it accepts the OwlMeans `AUTH-TOKEN` scheme AND plain `Bearer`, because a third-party client
+ *   configured with a URL sends the latter whatever the documentation says;
+ * - it intersects the token's scopes with its profile's on every request, so a token can never
+ *   outlive or outrank the person who minted it.
+ */
+export const makeAuthTokenGuard = (
+  alias: string = GUARD_AUTH_TOKEN, opts: AuthTokenGuardOptions = {}
+): GuardService => {
+  const touchInterval = opts.touchInterval ?? AUTH_TOKEN_TOUCH_INTERVAL
+
+  const present = (req: Partial<AbstractRequest>, prefix: string): string | null => {
+    const parsed = parseAuthorizationHeader(req.headers?.[AUTH_HEADER])
+    if (parsed == null) return null
+    if (parsed.scheme !== AUTH_TOKEN_SCHEME && parsed.scheme !== BEARER_SCHEME) return null
+
+    return isAccessToken(parsed.value, prefix) ? parsed.value : null
+  }
+
+  const service: GuardService = createService<GuardService>(alias, {
+    match: async req => {
+      const context = service.assertCtx<AuthTokenConfig, AuthTokenContext>()
+      if (req == null) return false
+      // A denied route refuses the credential outright. The refusal has to happen here rather
+      // than in the handler: a guard appended to a base reaches every child, and a child cannot
+      // drop what it inherited — so the only place left to say "not with this credential" is the
+      // moment the guard decides whether the request is its business at all.
+      if (opts.denyAliases != null && req.alias != null && opts.denyAliases.includes(req.alias)) {
+        return false
+      }
+
+      return present(req, prefixOf(context, opts)) != null
+    },
+
+    handle: async <T>(req: AbstractRequest, res: AbstractResponse<Auth>) => {
+      const context = service.assertCtx<AuthTokenConfig, AuthTokenContext>()
+      const prefix = prefixOf(context, opts)
+      const presented = present(req, prefix)
+      if (presented == null) return false as T
+
+      const tokens = context.resource<AccessTokenResource>(opts.resourceAlias ?? AUTH_TOKEN_RESOURCE)
+      const record = await tokens.load({ hash: hashAccessToken(presented) })
+      if (record == null) return false as T
+      if (record.revokedAt != null) return false as T
+      if (record.expiresAt != null && new Date(record.expiresAt) < new Date()) return false as T
+
+      // A token is only ever as good as the profile behind it. Reading the profile per request is
+      // what makes revoking a person's access revoke every token they ever minted, without any
+      // token record being touched.
+      const profiles = context.resource<IdentityProfileResource>(
+        opts.profileAlias ?? AUTH_IDENTITY_PROFILE
+      )
+      let profile: IdentityProfile | null = null
+      try {
+        profile = await profiles.load({ entityId: record.entityId, profileId: record.profileId })
+      } catch {
+        return false as T
+      }
+      if (profile == null) return false as T
+      if (profile.expiresAt != null && new Date(profile.expiresAt) < new Date()) return false as T
+
+      const profileScopes = profile.scopes ?? []
+      const scopes = profileScopes.includes(ALL_SCOPES)
+        ? record.scopes
+        : record.scopes.includes(ALL_SCOPES)
+          ? profileScopes
+          : record.scopes.filter(scope => profileScopes.includes(scope))
+
+      // `attachEntity` canonicalizes whatever it is given, but it resolves by NAME — so writing
+      // the current slug here costs one cached read and keeps the payload identical to the one a
+      // browser session produces.
+      let entitySlug = record.entityId
+      if (context.hasService(ENTITY_RESOLVER)) {
+        const resolver = context.service<EntityResolverService>(ENTITY_RESOLVER)
+        const entity = await resolver.byId(record.entityId)
+        if (entity != null) entitySlug = entity.slug
+      }
+
+      res.resolve({
+        // Never the secret: what a downstream reader sees is the display form, which is what a
+        // log or an audit trail can safely carry.
+        token: record.display,
+        type: AuthroizationType.AuthToken,
+        role: profile.role,
+        userId: record.userId,
+        profileId: record.profileId,
+        entitySlug,
+        scopes,
+        isUser: true,
+        source: context.cfg.service,
+        createdAt: new Date(record.createdAt),
+        ...(record.expiresAt != null ? { expiresAt: new Date(record.expiresAt) } : {}),
+      } as Auth)
+
+      const last = record.lastUsedAt == null ? 0 : new Date(record.lastUsedAt).getTime()
+      if (Date.now() - last > touchInterval) {
+        // Fire and forget: a usage timestamp is never a reason to fail a request, and awaiting it
+        // would put a database write on the critical path of every authenticated call.
+        void tokens.save({ ...record, lastUsedAt: new Date() })
+          .catch((e: unknown) => console.error('auth-token: lastUsedAt', e))
+      }
+
+      return true as T
+    },
+
+    /** Server-side guard: it verifies what arrives, it never produces a credential. */
+    authenticated: async () => null,
+  })
+
+  return service
+}

package/src/handlers/index.ts

@@ -0,0 +1,115 @@
+import { AuthForbidden, AuthroizationType, ALL_SCOPES, AuthRole } from '@owlmeans/auth'
+import {
+  AUTH_TOKEN_MAX_TTL, AUTH_TOKEN_RESOURCE
+} from '@owlmeans/auth-token'
+import type {
+  AccessTokenList, AccessTokenParams, AccessTokenRecord, AccessTokenView, CreateAccessToken,
+  IssuedAccessToken
+} from '@owlmeans/auth-token'
+import { requireEntityKey } from '@owlmeans/auth-common'
+import { handleBody, handleParams, handleRequest } from '@owlmeans/server-api'
+import { mintAccessToken } from '../hash.js'
+import { prefixOf } from '../guard.js'
+import type { AccessTokenResource, AuthTokenContext } from '../types.js'
+
+const view = (record: AccessTokenRecord): AccessTokenView => {
+  const { hash, ...rest } = record
+
+  return rest
+}
+
+const tokens = (ctx: AuthTokenContext): AccessTokenResource =>
+  ctx.resource<AccessTokenResource>(AUTH_TOKEN_RESOURCE)
+
+/**
+ * A token may never mint another token.
+ *
+ * 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. Creating and revoking
+ * therefore require a credential a person produced in a browser — which is also why the deployment
+ * names these 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.
+ */
+const refuseTokenAuth = (req: { auth?: { type?: string } }, what: string): void => {
+  if (req.auth?.type === AuthroizationType.AuthToken) {
+    throw new AuthForbidden(what)
+  }
+}
+
+export const listAccessTokens = handleRequest(async (req, context) => {
+  const ctx = context as AuthTokenContext
+  const entityId = requireEntityKey(req)
+  const profileId = req.auth?.profileId
+  if (profileId == null) throw new AuthForbidden('profile')
+
+  const result = await tokens(ctx).list({ entityId, profileId }, { size: 0 })
+
+  return {
+    items: result.items
+      .map(view)
+      .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()),
+  } satisfies AccessTokenList
+})
+
+export const createAccessToken = handleBody<CreateAccessToken>(async (payload, context, req) => {
+  const ctx = context as AuthTokenContext
+  refuseTokenAuth(req, 'token-mint')
+
+  const entityId = requireEntityKey(req)
+  const profileId = req.auth?.profileId
+  const userId = req.auth?.userId
+  if (profileId == null || userId == null) throw new AuthForbidden('profile')
+
+  const own = req.auth?.scopes ?? []
+  const scopes = payload.scopes ?? own
+  // A token is a delegation, so it can only ever narrow. Asking for a scope the caller does not
+  // hold is refused rather than silently dropped: a token that quietly grants less than it was
+  // asked for fails later, somewhere else, with an error about the wrong thing.
+  if (!own.includes(ALL_SCOPES) && scopes.some(scope => !own.includes(scope))) {
+    throw new AuthForbidden('scope')
+  }
+
+  // The SAME resolver the guard uses, so a minted token is one this deployment's guard claims.
+  const minted = mintAccessToken(prefixOf(ctx))
+  const now = new Date()
+  const record = await tokens(ctx).create({
+    hash: minted.hash,
+    display: minted.display,
+    name: payload.name,
+    userId,
+    profileId,
+    entityId,
+    scopes,
+    role: req.auth?.role ?? AuthRole.User,
+    createdAt: now,
+    ...(payload.expiresIn != null
+      ? { expiresAt: new Date(now.getTime() + Math.min(payload.expiresIn * 1000, AUTH_TOKEN_MAX_TTL)) }
+      : {}),
+  } as AccessTokenRecord)
+
+  // The only moment the plaintext exists outside the caller's own machine.
+  return { token: minted.token, record: view(record) } satisfies IssuedAccessToken
+})
+
+export const revokeAccessToken = handleParams<AccessTokenParams>(async (payload, context, req) => {
+  const ctx = context as AuthTokenContext
+  refuseTokenAuth(req, 'token-revoke')
+
+  const entityId = requireEntityKey(req)
+  const profileId = req.auth?.profileId
+  if (profileId == null) throw new AuthForbidden('profile')
+
+  const record = await tokens(ctx).load(payload.id)
+  // A token of another profile answers exactly as an unknown id does — an owner learns nothing
+  // about tokens that are not theirs, not even that one exists.
+  if (record == null || record.entityId !== entityId || record.profileId !== profileId) {
+    throw new AuthForbidden('token')
+  }
+
+  // Idempotent: revoking twice is what a retry looks like.
+  if (record.revokedAt == null) {
+    await tokens(ctx).save({ ...record, revokedAt: new Date(), updatedAt: new Date() })
+  }
+
+  return { id: payload.id }
+})

package/src/hash.ts

@@ -0,0 +1,27 @@
+import { AUTH_TOKEN_SECRET_BYTES, displayOf } from '@owlmeans/auth-token'
+import { base58 } from '@scure/base'
+import { sha256 } from '@noble/hashes/sha256'
+import { bytesToHex, randomBytes } from '@noble/hashes/utils'
+
+/**
+ * The stored form of a token.
+ *
+ * SHA-256 rather than a password hash on purpose: the input is 192 bits of machine-generated
+ * randomness, so there is no dictionary to slow down, and the hash is computed on every single
+ * API request — a deliberately slow function here would be a deliberate rate limit on the
+ * deployment's whole authenticated surface.
+ */
+export const hashAccessToken = (token: string): string => bytesToHex(sha256(new TextEncoder().encode(token)))
+
+export interface MintedToken {
+  token: string
+  hash: string
+  display: string
+}
+
+/** Mint one token: the plaintext (returned once), its hash (stored) and its display form. */
+export const mintAccessToken = (prefix: string): MintedToken => {
+  const token = `${prefix}${base58.encode(randomBytes(AUTH_TOKEN_SECRET_BYTES))}`
+
+  return { token, hash: hashAccessToken(token), display: displayOf(token, prefix) }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './consts.js'
+export * from './resource.js'
+export * from './guard.js'
+export * from './hash.js'
+export * from './coguard.js'
+export * from './append.js'
+export * from './handlers/index.js'
+export type * from './types.js'

package/src/resource.ts

@@ -0,0 +1,28 @@
+import { AUTH_TOKEN_COLLECTION, AUTH_TOKEN_RESOURCE } from '@owlmeans/auth-token'
+import type { AccessTokenRecord } from '@owlmeans/auth-token'
+import { makeMongoResource } from '@owlmeans/mongo-resource'
+import type { AccessTokenResource } from './types.js'
+
+/**
+ * Where access tokens live.
+ *
+ * `entityId` and `profileId` are stored as plain strings and only indexed — never declared as
+ * ObjectId references — because that is how the identity records they point at store them, and a
+ * reference declared on one side of a join and not the other finds nothing.
+ *
+ * No `$jsonSchema` is applied. The write path is one handler with a validated body, and a schema
+ * on the collection would have to be kept in step with a record the guard writes to on every
+ * request (`lastUsedAt`) for no protection the handler does not already give.
+ */
+export const makeAccessTokenResource = (dbAlias?: string): AccessTokenResource => {
+  const resource = makeMongoResource<AccessTokenRecord, AccessTokenResource>(
+    AUTH_TOKEN_RESOURCE, dbAlias, undefined, AUTH_TOKEN_COLLECTION
+  )
+  // The lookup every authenticated request makes. Unique because two records answering one
+  // presented secret would make revocation a coin toss.
+  resource.index('hash', { hash: 1 }, { unique: true })
+  resource.index('owner', { entityId: 1, profileId: 1 })
+  resource.index('expiresAt', { expiresAt: 1 }, { sparse: true })
+
+  return resource
+}

package/src/types.ts

@@ -0,0 +1,39 @@
+import type { AccessTokenRecord } from '@owlmeans/auth-token'
+import type { MongoResource } from '@owlmeans/mongo-resource'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+
+export type AccessTokenResource = MongoResource<AccessTokenRecord>
+
+export interface AuthTokenGuardOptions {
+  /**
+   * The prefix every token this deployment issues carries.
+   *
+   * Also what the guard claims on: a `Bearer` value without it is left to whatever other guard
+   * the route declares.
+   */
+  prefix?: string
+  /**
+   * Routes this guard refuses even when the entrypoint declares it.
+   *
+   * A guard added as a coguard reaches every child of the base it was added to, and a child
+   * cannot drop an inherited guard — so a route that must stay behind an interactive session
+   * (opening a checkout, starting an OAuth flow, minting another token) is named here. Refusing
+   * in `match` rather than in the handler is what makes the refusal a 401 rather than a route
+   * that quietly works.
+   */
+  denyAliases?: string[]
+  /** How often `lastUsedAt` may be written. Defaults to the package constant. */
+  touchInterval?: number
+  /** Resource alias holding the token records. */
+  resourceAlias?: string
+  /** Resource alias holding the identity profiles a token is bound to. */
+  profileAlias?: string
+}
+
+export interface AuthTokenConfig extends ServerConfig {
+  authToken?: {
+    prefix?: string
+  }
+}
+
+export type AuthTokenContext<C extends AuthTokenConfig = AuthTokenConfig> = ServerContext<C>

package/tests/coguard.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from 'bun:test'
+import { GUARD_AUTH_TOKEN } from '@owlmeans/auth-token'
+import { setupAuthTokenCoguard } from '../src/coguard.js'
+
+describe('@owlmeans/server-auth-token — the coguard', () => {
+  test('appends to a guarded entrypoint and leaves the primary guard first', () => {
+    const entrypoints = [{ guards: ['auth'] }]
+    setupAuthTokenCoguard(entrypoints)
+
+    expect(entrypoints[0].guards).toEqual(['auth', GUARD_AUTH_TOKEN])
+  })
+
+  test('leaves an unguarded entrypoint unguarded', () => {
+    // A public route stays public: adding a guard here would turn an open page into a 401.
+    const entrypoints: Array<{ guards?: string[] }> = [{}, { guards: [] }]
+    setupAuthTokenCoguard(entrypoints)
+
+    expect(entrypoints[0].guards).toBeUndefined()
+    expect(entrypoints[1].guards).toEqual([])
+  })
+
+  test('is idempotent — a second pass adds nothing', () => {
+    const entrypoints = [{ guards: ['auth'] }]
+    setupAuthTokenCoguard(entrypoints)
+    setupAuthTokenCoguard(entrypoints)
+
+    expect(entrypoints[0].guards).toEqual(['auth', GUARD_AUTH_TOKEN])
+  })
+
+  test('honours a custom guard alias', () => {
+    const entrypoints = [{ guards: ['auth'] }]
+    setupAuthTokenCoguard(entrypoints, 'other-guard')
+
+    expect(entrypoints[0].guards).toEqual(['auth', 'other-guard'])
+  })
+})