@owlmeans/server-auth-token 0.1.18-rc.9 → 0.1.18

package/src/guard.ts

@@ -1,8 +1,8 @@
 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
+  AUTH_TOKEN_SCHEME, AUTH_TOKEN_RESOURCE, AUTH_TOKEN_TOUCH_INTERVAL,
+  BEARER_SCHEME, GUARD_AUTH_TOKEN, tokenFormatHelper
 } from '@owlmeans/auth-token'
 import { AUTH_HEADER } from '@owlmeans/auth'
 import { ENTITY_RESOLVER } from '@owlmeans/auth-common'
@@ -11,12 +11,12 @@ 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 { tokenHashHelper } from './hash.js'
+import { prefixOf } from './prefix.js'
 import type { AccessTokenResource, AuthTokenConfig, AuthTokenContext, AuthTokenGuardOptions } from './types.js'
+import { logger, logThrottle } from '@owlmeans/log'
 
-/** 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
+const log = logger('server-auth-token')
 
 /**
  * The guard that verifies a long-lived access token.
@@ -39,14 +39,27 @@ export const prefixOf = (context: AuthTokenContext, opts?: AuthTokenGuardOptions
 export const makeAuthTokenGuard = (
   alias: string = GUARD_AUTH_TOKEN, opts: AuthTokenGuardOptions = {}
 ): GuardService => {
+  /**
+   * A presented access token the guard did not accept. Never the token, not even its display form:
+   * its record id only. Once a minute per token and reason — a client retrying a revoked token calls every second.
+   */
+  const refuse = (reason: string, record?: { id?: string, entityId?: string }): false => {
+    if (logThrottle(`auth-token:${reason}:${record?.id ?? ''}`, 60_000)) {
+      log.warn('Access token refused', {
+        reason, tokenId: record?.id, entityId: record?.entityId,
+      }, { event: 'auth.refused' })
+    }
+    return false
+  }
+
   const touchInterval = opts.touchInterval ?? AUTH_TOKEN_TOUCH_INTERVAL
 
   const present = (req: Partial<AbstractRequest>, prefix: string): string | null => {
-    const parsed = parseAuthorizationHeader(req.headers?.[AUTH_HEADER])
+    const parsed = tokenFormatHelper.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
+    return tokenFormatHelper.isAccessToken(parsed.value, prefix) ? parsed.value : null
   }
 
   const service: GuardService = createService<GuardService>(alias, {
@@ -71,10 +84,20 @@ export const makeAuthTokenGuard = (
       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
+      const record = await tokens.load({ hash: tokenHashHelper.hashAccessToken(presented) })
+      if (record == null) return refuse('unknown') as T
+      if (record.revokedAt != null) return refuse('revoked', record) as T
+      if (record.expiresAt != null && new Date(record.expiresAt) < new Date()) return refuse('expired', record) as T
+      // A token minted through an OAuth grant carries the resource(s) it was issued FOR. A token
+      // with no audience is the ordinary hand-minted kind and is admitted everywhere its scopes
+      // reach, exactly as before this check existed — the guard has to OPT IN with `resources` to
+      // narrow anything, so a deployment that never touches this option sees no change at all.
+      const resources = typeof opts.resources === 'function' ? opts.resources(context) : opts.resources
+      if (record.audience != null && record.audience.length > 0
+        && resources != null && resources.length > 0
+        && !record.audience.some(resource => resources.includes(resource))) {
+        return refuse('audience', record) 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
@@ -86,10 +109,10 @@ export const makeAuthTokenGuard = (
       try {
         profile = await profiles.load({ entityId: record.entityId, profileId: record.profileId })
       } catch {
-        return false as T
+        return refuse('profile-unreadable', record) as T
       }
-      if (profile == null) return false as T
-      if (profile.expiresAt != null && new Date(profile.expiresAt) < new Date()) return false as T
+      if (profile == null) return refuse('profile', record) as T
+      if (profile.expiresAt != null && new Date(profile.expiresAt) < new Date()) return refuse('profile-expired', record) as T
 
       const profileScopes = profile.scopes ?? []
       const scopes = profileScopes.includes(ALL_SCOPES)
@@ -129,7 +152,7 @@ export const makeAuthTokenGuard = (
         // 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))
+          .catch((e: unknown) => { log.warn('Access token lastUsedAt not saved', { tokenId: record.id, error: e }) })
       }
 
       return true as T

package/src/handlers/create.ts

@@ -0,0 +1,21 @@
+import { AuthForbidden, AuthRole } from '@owlmeans/auth'
+import type { AuthTokenEntrypoints } from '@owlmeans/auth-token'
+import { makeEntityScope } from '@owlmeans/auth-common'
+import { handlers } from '@owlmeans/server-api'
+import type { AuthTokenContext } from '../types.js'
+import { accessTokenIssuerOf } from './issue.js'
+import { refuseTokenAuth } from './refuse.js'
+
+export const createAccessToken = (protocol: AuthTokenEntrypoints['create']) => handlers<AuthTokenContext>().body(protocol, async (payload, context, req) => {
+  const ctx = context as AuthTokenContext
+  refuseTokenAuth(req, 'token-mint')
+
+  const entityId = makeEntityScope(req).requireEntityKey()
+  const profileId = req.auth?.profileId
+  const userId = req.auth?.userId
+  if (profileId == null || userId == null) throw new AuthForbidden('profile')
+
+  return accessTokenIssuerOf(ctx).issueAccessToken({
+    entityId, profileId, userId, role: req.auth?.role ?? AuthRole.User, scopes: req.auth?.scopes ?? [],
+  }, payload)
+})

package/src/handlers/index.ts

@@ -1,115 +1,17 @@
-import { AuthForbidden, AuthroizationType, ALL_SCOPES, AuthRole } from '@owlmeans/auth'
-import {
-  AUTH_TOKEN_MAX_TTL, AUTH_TOKEN_RESOURCE
-} from '@owlmeans/auth-token'
-import type {
-  AccessTokenList, AccessTokenRecord, AccessTokenView, IssuedAccessToken
-} from '@owlmeans/auth-token'
-import { requireEntityKey } from '@owlmeans/auth-common'
-import { handlers } from '@owlmeans/server-api'
-import { mintAccessToken } from '../hash.js'
-import { prefixOf } from '../guard.js'
-import type { AccessTokenResource, AuthTokenContext } from '../types.js'
-import type { AuthTokenEntrypoints } from '@owlmeans/auth-token'
-
-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 = (protocol: AuthTokenEntrypoints['list']) => handlers<AuthTokenContext>().request(protocol, 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 = (protocol: AuthTokenEntrypoints['create']) => handlers<AuthTokenContext>().body(protocol, 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 = (protocol: AuthTokenEntrypoints['revoke']) => handlers<AuthTokenContext>().params(protocol, 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 }
-})
+import type { IssuedAccessToken } from '@owlmeans/auth-token'
+import type { AuthTokenContext } from '../types.js'
+import { accessTokenIssuerOf } from './issue.js'
+import type { IssueAccessTokenRequest, IssueAccessTokenSubject } from './types.js'
+
+export * from './refuse.js'
+export * from './issue.js'
+export * from './list.js'
+export * from './create.js'
+export * from './revoke.js'
+
+export type { IssueAccessTokenRequest, IssueAccessTokenSubject, RevokeAccessTokenOptions } from './types.js'
+
+/** @deprecated compat:factory-refactor — use `accessTokenIssuerOf(ctx).issueAccessToken(…)` */
+export const issueAccessToken = async (
+  ctx: AuthTokenContext, subject: IssueAccessTokenSubject, payload: IssueAccessTokenRequest
+): Promise<IssuedAccessToken> => await accessTokenIssuerOf(ctx).issueAccessToken(subject, payload)

package/src/handlers/issue.ts

@@ -0,0 +1,50 @@
+import { AuthForbidden, ALL_SCOPES } from '@owlmeans/auth'
+import { AUTH_TOKEN_MAX_TTL, type AccessTokenRecord, type IssuedAccessToken } from '@owlmeans/auth-token'
+import { memoHelper } from '@owlmeans/context'
+import { tokenHashHelper } from '../hash.js'
+import { prefixOf } from '../prefix.js'
+import type { AuthTokenContext } from '../types.js'
+import type { AccessTokenIssuer, IssueAccessTokenRequest, IssueAccessTokenSubject } from './types.js'
+import { tokenRecordUtils } from './utils.js'
+
+export const makeAccessTokenIssuer = (ctx: AuthTokenContext): AccessTokenIssuer => {
+  const issueAccessToken = async (
+    subject: IssueAccessTokenSubject, payload: IssueAccessTokenRequest
+  ): Promise<IssuedAccessToken> => {
+    const own = subject.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 = tokenHashHelper.mintAccessToken(prefixOf(ctx))
+    const now = new Date()
+    const record = await tokenRecordUtils.tokens(ctx).create({
+      hash: minted.hash,
+      display: minted.display,
+      name: payload.name,
+      userId: subject.userId,
+      profileId: subject.profileId,
+      entityId: subject.entityId,
+      scopes,
+      role: subject.role,
+      createdAt: now,
+      ...(payload.audience != null ? { audience: payload.audience } : {}),
+      ...(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: tokenRecordUtils.view(record) } satisfies IssuedAccessToken
+  }
+
+  return { issueAccessToken }
+}
+
+/** The token issuer of a context — one per context. */
+export const accessTokenIssuerOf = memoHelper.oncePer(makeAccessTokenIssuer)

package/src/handlers/list.ts

@@ -0,0 +1,21 @@
+import { AuthForbidden } from '@owlmeans/auth'
+import type { AccessTokenList, AuthTokenEntrypoints } from '@owlmeans/auth-token'
+import { makeEntityScope } from '@owlmeans/auth-common'
+import { handlers } from '@owlmeans/server-api'
+import type { AuthTokenContext } from '../types.js'
+import { tokenRecordUtils } from './utils.js'
+
+export const listAccessTokens = (protocol: AuthTokenEntrypoints['list']) => handlers<AuthTokenContext>().request(protocol, async (req, context) => {
+  const ctx = context as AuthTokenContext
+  const entityId = makeEntityScope(req).requireEntityKey()
+  const profileId = req.auth?.profileId
+  if (profileId == null) throw new AuthForbidden('profile')
+
+  const result = await tokenRecordUtils.tokens(ctx).list({ entityId, profileId }, { size: 0 })
+
+  return {
+    items: result.items
+      .map(tokenRecordUtils.view)
+      .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()),
+  } satisfies AccessTokenList
+})

package/src/handlers/refuse.ts

@@ -0,0 +1,20 @@
+import { AuthForbidden, AuthroizationType } from '@owlmeans/auth'
+
+/**
+ * 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.
+ *
+ * Exported because an OAuth authorization server's consent-approval handler
+ * (`@owlmeans/server-oauth`) mints tokens too and needs the exact same guard, over a session it
+ * verified itself rather than a route this package bound.
+ */
+export const refuseTokenAuth = (req: { auth?: { type?: string } }, what: string): void => {
+  if (req.auth?.type === AuthroizationType.AuthToken) {
+    throw new AuthForbidden(what)
+  }
+}

package/src/handlers/revoke.ts

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

package/src/handlers/types.ts

@@ -0,0 +1,40 @@
+import { AuthRole } from '@owlmeans/auth'
+import type { CreateAccessToken, IssuedAccessToken } from '@owlmeans/auth-token'
+
+/** Whoever is minting the token — read once, by whichever caller resolved the session. */
+export interface IssueAccessTokenSubject {
+  entityId: string
+  userId: string
+  profileId: string
+  role: AuthRole
+  /** The subject's OWN scopes — minting can only narrow, never widen, this set. */
+  scopes: string[]
+}
+
+export interface IssueAccessTokenRequest extends CreateAccessToken {
+  /**
+   * The resource(s) this token is FOR (RFC 8707), when it is minted through an OAuth grant.
+   * Absent for a token minted by hand — the ordinary, unrestricted kind.
+   */
+  audience?: string[]
+}
+
+/** Token issuance over one context's store — the one path every minting caller goes through. */
+export interface AccessTokenIssuer {
+  /**
+   * Mint one token for `subject`, exactly what `createAccessToken` does over an HTTP body — pulled
+   * out so a second caller (an OAuth token endpoint) can mint the SAME shape of record over a
+   * session it authenticated its own way, without a duplicate copy of the narrowing rule or the
+   * TTL clamp silently drifting from this one.
+   */
+  issueAccessToken: (subject: IssueAccessTokenSubject, payload: IssueAccessTokenRequest) => Promise<IssuedAccessToken>
+}
+
+/** How a deployment binds `revokeAccessToken`. */
+export interface RevokeAccessTokenOptions {
+  /**
+   * Let an access token revoke one of its own person's tokens (itself included). Defaults to
+   * `false`: only an interactive session revokes. Ownership is checked the same either way.
+   */
+  allowAccessTokens?: boolean
+}

package/src/handlers/utils/types.ts

@@ -0,0 +1,10 @@
+import type { AccessTokenRecord, AccessTokenView } from '@owlmeans/auth-token'
+import type { AccessTokenResource, AuthTokenContext } from '../../types.js'
+
+/** What every token handler shares: the store and the view a caller may see. */
+export interface TokenRecordUtils {
+  /** A record without its hash — the hash never leaves the server. */
+  view: (record: AccessTokenRecord) => AccessTokenView
+  /** The token store of a context. */
+  tokens: (ctx: AuthTokenContext) => AccessTokenResource
+}

package/src/handlers/utils.ts

@@ -0,0 +1,18 @@
+import { AUTH_TOKEN_RESOURCE, type AccessTokenRecord, type AccessTokenView } from '@owlmeans/auth-token'
+import type { AccessTokenResource, AuthTokenContext } from '../types.js'
+import type { TokenRecordUtils } from './utils/types.js'
+
+export const createTokenRecordUtils = (): TokenRecordUtils => {
+  const view = (record: AccessTokenRecord): AccessTokenView => {
+    const { hash, ...rest } = record
+
+    return rest
+  }
+
+  const tokens = (ctx: AuthTokenContext): AccessTokenResource =>
+    ctx.resource<AccessTokenResource>(AUTH_TOKEN_RESOURCE)
+
+  return { view, tokens }
+}
+
+export const tokenRecordUtils = createTokenRecordUtils()

package/src/hash/types.ts

@@ -0,0 +1,16 @@
+import type { MintedToken } from '../types.js'
+
+/** Access tokens minted and stored: the plaintext once, the hash forever. */
+export interface TokenHashHelper {
+  /**
+   * 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.
+   */
+  hashAccessToken: (token: string) => string
+  /** Mint one token: the plaintext (returned once), its hash (stored) and its display form. */
+  mintAccessToken: (prefix: string) => MintedToken
+}

package/src/hash.ts

@@ -1,27 +1,23 @@
-import { AUTH_TOKEN_SECRET_BYTES, displayOf } from '@owlmeans/auth-token'
+import { AUTH_TOKEN_SECRET_BYTES, tokenFormatHelper } from '@owlmeans/auth-token'
 import { base58 } from '@scure/base'
-import { sha256 } from '@noble/hashes/sha256'
-import { bytesToHex, randomBytes } from '@noble/hashes/utils'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { bytesToHex, randomBytes } from '@noble/hashes/utils.js'
+import type { MintedToken } from './types.js'
+import type { TokenHashHelper } from './hash/types.js'
 
-/**
- * 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 const createTokenHashHelper = (): TokenHashHelper => {
+  const hashAccessToken = (token: string): string => bytesToHex(sha256(new TextEncoder().encode(token)))
 
-export interface MintedToken {
-  token: string
-  hash: string
-  display: string
-}
+  const mintAccessToken = (prefix: string): MintedToken => {
+    const token = `${prefix}${base58.encode(randomBytes(AUTH_TOKEN_SECRET_BYTES))}`
 
-/** 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: tokenFormatHelper.displayOf(token, prefix) }
+  }
 
-  return { token, hash: hashAccessToken(token), display: displayOf(token, prefix) }
+  return { hashAccessToken, mintAccessToken }
 }
+
+export const tokenHashHelper = createTokenHashHelper()
+
+/** @deprecated compat:factory-refactor — use `tokenHashHelper.hashAccessToken(…)` */
+export const hashAccessToken = (token: string): string => tokenHashHelper.hashAccessToken(token)

package/src/index.ts

@@ -1,8 +1,11 @@
 export * from './consts.js'
 export * from './resource.js'
+export * from './prefix.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 './handlers/types.js'
 export type * from './types.js'
+export type * from './hash/types.js'

package/src/prefix.ts

@@ -0,0 +1,6 @@
+import { AUTH_TOKEN_DEFAULT_PREFIX } from '@owlmeans/auth-token'
+import type { 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

package/src/types.ts

@@ -28,6 +28,21 @@ export interface AuthTokenGuardOptions {
   resourceAlias?: string
   /** Resource alias holding the identity profiles a token is bound to. */
   profileAlias?: string
+  /**
+   * The resource(s) this guard speaks for, opting it into audience admission.
+   *
+   * Left unset (the default), the guard admits every token whatever its `audience` — full
+   * backward compatibility for a deployment that never mints an audience-restricted token. Set
+   * it to the canonical resource URI(s) this route surface serves, and a token issued FOR a
+   * different resource (an OAuth-issued, MCP-only token, say) is refused here rather than
+   * quietly working everywhere the profile's scopes would otherwise reach.
+   *
+   * A function is resolved with the live context on every request rather than once at
+   * registration time — `appendAuthTokenGuard` runs from `makeContext`, before a hostname a
+   * Kubernetes secret mount populates is necessarily readable yet, and this guard's `handle`
+   * already runs per-request regardless.
+   */
+  resources?: string[] | ((context: AuthTokenContext) => string[])
 }
 
 export interface AuthTokenConfig extends ServerConfig {
@@ -37,3 +52,9 @@ export interface AuthTokenConfig extends ServerConfig {
 }
 
 export type AuthTokenContext<C extends AuthTokenConfig = AuthTokenConfig> = ServerContext<C>
+
+export interface MintedToken {
+  token: string
+  hash: string
+  display: string
+}