@ultimat3/auth 29.3.2 → 30.0.0

package/src/cose-key.ts

@@ -0,0 +1,129 @@
+// Single responsibility: a COSE_Key (RFC 9053) a passkey registered, as a WebCrypto key that can
+// check its signatures — ES256 (P-256, the algorithm every platform authenticator uses) and RS256
+// (Windows Hello's). The algorithm comes from the KEY, never from the assertion: a signature cannot
+// choose how it is checked. Every malformed input answers `null`; the caller owns the refusal.
+
+import { base64Url } from './base64url';
+import { type CborValue, decodeCbor } from './cbor';
+
+/** COSE algorithm identifiers this package verifies. Offered in this order at registration. */
+export const COSE_ES256 = -7;
+export const COSE_RS256 = -257;
+export const PASSKEY_ALGORITHMS: readonly number[] = Object.freeze([COSE_ES256, COSE_RS256]);
+
+const KTY_EC2 = 2;
+const KTY_RSA = 3;
+const CRV_P256 = 1;
+/** RSA keys below this are not a credential anybody should accept in 2026. */
+const MIN_RSA_MODULUS_BYTES = 256;
+
+export interface PasskeyPublicKey {
+  readonly algorithm: number;
+  readonly key: CryptoKey;
+}
+
+const bytesAt = (
+  map: ReadonlyMap<number | string, CborValue>,
+  label: number,
+): Uint8Array | null => {
+  const value = map.get(label);
+  return value instanceof Uint8Array ? value : null;
+};
+
+/** The stored COSE bytes as a verifying key, or `null` when they are not one this package checks. */
+export async function importCoseKey(cose: Uint8Array): Promise<PasskeyPublicKey | null> {
+  const decoded = decodeCbor(cose);
+  if (!(decoded instanceof Map)) return null;
+  const kty = decoded.get(1);
+  const algorithm = decoded.get(3);
+  try {
+    if (kty === KTY_EC2 && algorithm === COSE_ES256) {
+      const x = bytesAt(decoded, -2);
+      const y = bytesAt(decoded, -3);
+      if (decoded.get(-1) !== CRV_P256 || x?.length !== 32 || y?.length !== 32) return null;
+      const jwk = { kty: 'EC', crv: 'P-256', x: base64Url(x), y: base64Url(y) };
+      const key = await crypto.subtle.importKey(
+        'jwk',
+        jwk,
+        { name: 'ECDSA', namedCurve: 'P-256' },
+        false,
+        ['verify'],
+      );
+      return { algorithm, key };
+    }
+    if (kty === KTY_RSA && algorithm === COSE_RS256) {
+      const n = bytesAt(decoded, -1);
+      const e = bytesAt(decoded, -2);
+      if (n === null || e === null || n.length < MIN_RSA_MODULUS_BYTES || e.length === 0) {
+        return null;
+      }
+      const jwk = { kty: 'RSA', n: base64Url(n), e: base64Url(e) };
+      const key = await crypto.subtle.importKey(
+        'jwk',
+        jwk,
+        { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+        false,
+        ['verify'],
+      );
+      return { algorithm, key };
+    }
+  } catch {
+    // A point off the curve, or a modulus WebCrypto refuses: not a key.
+    return null;
+  }
+  return null;
+}
+
+/** `false` for every failure, the malformed signature included — never a throw on foreign bytes. */
+export async function verifyCoseSignature(
+  checker: PasskeyPublicKey,
+  signature: Uint8Array,
+  signed: Uint8Array,
+): Promise<boolean> {
+  try {
+    if (checker.algorithm === COSE_ES256) {
+      const raw = ecdsaDerToRaw(signature);
+      if (raw === null) return false;
+      return await crypto.subtle.verify(
+        { name: 'ECDSA', hash: 'SHA-256' },
+        checker.key,
+        raw,
+        new Uint8Array(signed),
+      );
+    }
+    return await crypto.subtle.verify(
+      'RSASSA-PKCS1-v1_5',
+      checker.key,
+      new Uint8Array(signature),
+      new Uint8Array(signed),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * An authenticator's ES256 signature is ASN.1 DER — `SEQUENCE { INTEGER r, INTEGER s }` — and
+ * WebCrypto checks the raw 64-byte `r || s`. Strict DER: minimal lengths, no trailing bytes, each
+ * integer positive and at most 32 bytes once its sign byte is dropped.
+ */
+export function ecdsaDerToRaw(der: Uint8Array): Uint8Array<ArrayBuffer> | null {
+  if (der.length < 8 || der[0] !== 0x30 || der[1] !== der.length - 2) return null;
+  const raw = new Uint8Array(64);
+  let at = 2;
+  for (const offset of [0, 32]) {
+    if (der[at] !== 0x02) return null;
+    const length = der[at + 1] ?? 0;
+    const start = at + 2;
+    if (length === 0 || length > 33 || start + length > der.length) return null;
+    let integer = der.subarray(start, start + length);
+    // Negative, or a leading zero the next byte did not need: not DER.
+    if ((integer[0] ?? 0) & 0x80) return null;
+    if (integer[0] === 0 && integer.length > 1 && ((integer[1] ?? 0) & 0x80) === 0) return null;
+    if (integer[0] === 0 && integer.length > 1) integer = integer.subarray(1);
+    if (integer.length > 32) return null;
+    raw.set(integer, offset + 32 - integer.length);
+    at = start + length;
+  }
+  return at === der.length ? raw : null;
+}

package/src/errors.ts

@@ -30,6 +30,15 @@ export const AUTH_OWNED_ERROR_CODES = [
   'X_AUTH_LIMITER_NOT_SHARED',
   'X_AUTH_LIMITER_POLICY_MISMATCH',
   'X_MFA_SECRET_UNSEALED',
+  'X_AUTH_SIGN_IN_UNCONFIGURED',
+  'X_AUTH_SERVER_INVALID',
+  'X_AUTH_CONSENT_INVALID',
+  'X_AUTH_GRANT_DISABLED',
+  'X_VERIFICATION_PURPOSE_INVALID',
+  'X_VERIFICATION_PURPOSE_UNKNOWN',
+  'X_PASSKEY_INVALID',
+  'X_PASSKEY_CHALLENGE_EXPIRED',
+  'X_PASSKEY_STEP_UP_REQUIRED',
 ] as const;
 
 /**
@@ -76,6 +85,20 @@ export const AUTH_ERROR_TITLES: Readonly<Record<AuthOwnedErrorCode, string>> = {
   X_AUTH_LIMITER_NOT_SHARED: 'the lockout is declared fleet-wide and the limiter is per-process',
   X_AUTH_LIMITER_POLICY_MISMATCH: 'the limiter in use enforces other numbers than the app declared',
   X_MFA_SECRET_UNSEALED: 'a stored totp secret is not sealed, so it is never read as one',
+  X_AUTH_SIGN_IN_UNCONFIGURED:
+    'a people-facing role started with no sign-in settings outside development and test',
+  X_AUTH_SERVER_INVALID: 'the authorization server was configured with a field it cannot run on',
+  X_AUTH_CONSENT_INVALID: 'a consent was approved for a request the authorization server refuses',
+  X_AUTH_GRANT_DISABLED: 'a token request named a grant this authorization server does not enable',
+  X_VERIFICATION_PURPOSE_INVALID: 'a verification purpose was declared twice or without a template',
+  X_VERIFICATION_PURPOSE_UNKNOWN:
+    'a verification token was issued or consumed for a purpose nothing declared',
+  X_PASSKEY_INVALID:
+    'a passkey ceremony response failed its signature, origin, rp id, flag or counter check',
+  X_PASSKEY_CHALLENGE_EXPIRED:
+    'a passkey ceremony named a challenge that is unknown, already used or past its ttl',
+  X_PASSKEY_STEP_UP_REQUIRED:
+    'a sensitive action ran without a fresh user-verified passkey proof for its digest',
 };
 
 // Registered unconditionally, in one call: a second package claiming a code auth owns has to fail
@@ -234,6 +257,21 @@ export const mfaSecretUnsealed = (): AuthError =>
     fix: 'x auth seal-mfa --json',
   });
 
+/**
+ * The boot guard `x g sign-in` writes, refusing a people-facing role (`web`, `sync`) outside
+ * development and test when the app's sign-in settings are unset: started anyway, every
+ * policy-protected route answers 401 and nobody can sign in to fix it. The guard is the app's —
+ * an API-only app has no sign-in — so the code is here and the decision to throw it is not.
+ */
+export const signInUnconfigured = (role: string, missing: readonly string[]): AuthError =>
+  new AuthError({
+    code: 'X_AUTH_SIGN_IN_UNCONFIGURED',
+    cause: `the ${renderCauseValue(role)} role serves people and sign-in is unconfigured: ${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} unset`,
+    // The env edit itself: `x env example` is an app-tree command, absent from a deployed image.
+    fix: `export <KEY>="<value>"   # each key the cause names, in the role's deployed environment (compose environment:, the platform's secrets), then restart the role`,
+    meta: { role, missing: [...missing] },
+  });
+
 /**
  * `defineAuth({ mfa: { required: true } })`, refused where it is declared. The option read as a
  * security guarantee — "this deployment requires a second factor" — and nothing in this package
@@ -254,6 +292,19 @@ export const mfaRequiredUnenforceable = (): AuthError =>
     fix: 'drop required from defineAuth({ mfa }) and gate it in your own sign-in handler, which is where the enrolment route lives: if (user.mfaSecret === null) send them to enrolTotp(auth, { account: user.email }) instead of createSession(auth.sessions, ...)',
   });
 
+/**
+ * A `totpReplay` with no `claim`: a guard written for the `isUsed`/`remember` pair, which could not
+ * be atomic across a network. `X_CONFIG_INVALID` is core's code, borrowed like the one above.
+ */
+export const totpReplayGuardInvalid = (): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause:
+      'defineAuth({ totpReplay }) has no claim function, so completeMfa has no way to spend a TOTP step',
+    fix: 'defineAuth({ totpReplay: { claim: (subject, step, at) => firstUse(subject, step, at) } })   # claim(subject, step, at) replaces isUsed/remember, answering true the first time and false for a replay; or drop the totpReplay option on a framework-booted process',
+    meta: { option: 'totpReplay' },
+  });
+
 /**
  * `login(auth, { handle })` on an app whose `defineAuth` named no `handles` lookup. Refused before
  * any bucket is reserved or any hash run: this is a wiring fault, never a failed guess.

package/src/grant-authorization-code.ts

@@ -0,0 +1,113 @@
+// Single responsibility: the two person-grant legs of `POST /oauth/token` — a code for tokens
+// (RFC 6749 §4.1.3 + PKCE) and a refresh token for new ones (§6, OAuth 2.1 rotation). The rules:
+// a code is single use and its replay revokes what it minted; a retired refresh token's replay
+// revokes the whole grant; the redirect and the resource must be the ones the code was bound to.
+
+import type { ResolvedAuthServerConfig } from './authorization-server-config';
+import {
+  firstRefresh,
+  pkceMatches,
+  refreshRecord,
+  refused,
+  type TokenOutcome,
+  tokenAnswer,
+} from './authorization-server-tokens';
+import type { AuthServerClient } from './authorization-server-types';
+import { sha256Hex } from './tokens';
+
+type Form = ReadonlyMap<string, string>;
+
+const invalidGrant = (description: string): TokenOutcome => refused('invalid_grant', description);
+
+export async function exchangeCode(
+  config: ResolvedAuthServerConfig,
+  form: Form,
+  client: AuthServerClient,
+): Promise<TokenOutcome> {
+  const code = form.get('code');
+  const verifier = form.get('code_verifier');
+  if (code === undefined || verifier === undefined) {
+    return refused('invalid_request', 'code and code_verifier are required');
+  }
+  const now = config.clock.now();
+  const taken = await config.store.takeCode(sha256Hex(code), now);
+  if (taken === null) return invalidGrant('the code is unknown');
+  const record = taken.code;
+  if (!taken.fresh) {
+    // Somebody holds a copy of a code that was already redeemed: whatever it minted is suspect.
+    await config.store.revokeGrant(record.grantId, now);
+    config.emit({ kind: 'code-replayed', clientId: record.clientId });
+    return invalidGrant('the code was already used; the grant it minted is revoked');
+  }
+  if (record.clientId !== client.clientId)
+    return invalidGrant('the code was issued to another client');
+  if (record.expiresAt.getTime() <= now.getTime()) return invalidGrant('the code expired');
+  if (form.get('redirect_uri') !== record.redirectUri) {
+    return invalidGrant('redirect_uri is not the one the code was issued for');
+  }
+  if (!pkceMatches(verifier, record.codeChallenge)) {
+    return invalidGrant('the code_verifier does not match the code_challenge');
+  }
+  const resource = form.get('resource');
+  if (resource !== undefined && resource !== record.resource) {
+    return refused('invalid_target', 'the resource is not the one the grant is bound to');
+  }
+  const grant = await config.store.getGrant(record.grantId);
+  if (grant === null || grant.revokedAt !== null) return invalidGrant('the grant is revoked');
+  const refresh = await firstRefresh(config, grant.id);
+  return tokenAnswer(config, grant, config.accessSeconds, refresh);
+}
+
+export async function exchangeRefresh(
+  config: ResolvedAuthServerConfig,
+  form: Form,
+  client: AuthServerClient,
+): Promise<TokenOutcome> {
+  const presented = form.get('refresh_token');
+  if (presented === undefined) return refused('invalid_request', 'refresh_token is required');
+  const now = config.clock.now();
+  const hash = sha256Hex(presented);
+  const token = await config.store.getToken(hash);
+  if (token === null || token.kind !== 'refresh')
+    return invalidGrant('the refresh token is unknown');
+  if (token.retiredAt !== null) return replayed(config, token.grantId, client.clientId);
+  const grant = await config.store.getGrant(token.grantId);
+  if (grant === null || grant.revokedAt !== null) return invalidGrant('the grant is revoked');
+  if (grant.clientId !== client.clientId)
+    return invalidGrant('the token was issued to another client');
+  if (grant.refreshedAt.getTime() + config.refreshIdleMs <= now.getTime()) {
+    return invalidGrant('the grant sat idle past its refresh window');
+  }
+  const scope = form.get('scope');
+  if (
+    scope !== undefined &&
+    scope.split(' ').sort().join(' ') !== [...grant.scopes].sort().join(' ')
+  ) {
+    // A narrower refresh would need per-token scopes; the honest answer is to say so.
+    return refused(
+      'invalid_scope',
+      'a refresh keeps the granted scope; authorize again to change it',
+    );
+  }
+  const resource = form.get('resource');
+  if (resource !== undefined && resource !== grant.resource) {
+    return refused('invalid_target', 'the resource is not the one the grant is bound to');
+  }
+  const next = refreshRecord(config, grant.id);
+  const rotation = await config.store.rotateRefresh(hash, next.record, now);
+  if (rotation.outcome === 'replayed') return replayed(config, rotation.grantId, client.clientId);
+  if (rotation.outcome === 'unknown') return invalidGrant('the refresh token is unknown');
+  await config.store.touchGrant(grant.id, now);
+  return tokenAnswer(config, grant, config.accessSeconds, next.token);
+}
+
+/** A retired refresh token came back: one of two holders is a thief, so neither keeps the grant. */
+async function replayed(
+  config: ResolvedAuthServerConfig,
+  grantId: string,
+  clientId: string,
+): Promise<TokenOutcome> {
+  await config.store.revokeGrant(grantId, config.clock.now());
+  config.emit({ kind: 'refresh-replayed', clientId });
+  return invalidGrant('the refresh token was already rotated; the grant is revoked');
+}

package/src/grant-client-credentials.ts

@@ -0,0 +1,55 @@
+// Single responsibility: RFC 6749 §4.4 — a machine with no person to consent (a partner's nightly
+// sync) trades its own secret for a short-lived access token. Confidential clients only, the
+// subject is the client itself, scopes are its registered set narrowed by the request, and there
+// is never a refresh token: the secret IS the long-lived credential, so a second one is a liability.
+
+import type { ResolvedAuthServerConfig } from './authorization-server-config';
+import { screenResource } from './authorization-server-request';
+import { refused, type TokenOutcome, tokenAnswer } from './authorization-server-tokens';
+import type { AuthServerClient } from './authorization-server-types';
+import { randomToken } from './tokens';
+
+export async function exchangeClientCredentials(
+  config: ResolvedAuthServerConfig,
+  form: ReadonlyMap<string, string>,
+  client: AuthServerClient,
+): Promise<TokenOutcome> {
+  // The wire already proved the secret; a PUBLIC client has none to prove, so it never gets here.
+  if (client.secretHash === null) {
+    return refused('unauthorized_client', 'client_credentials needs a confidential client', 401);
+  }
+  if (!client.grantTypes.includes('client_credentials')) {
+    return refused('unauthorized_client', 'this client may not use client_credentials');
+  }
+  // An empty registration is the server's whole set, as `AuthServerClient.scopes` documents.
+  const registered =
+    client.scopes.length === 0
+      ? [...config.scopes]
+      : client.scopes.filter((scope) => config.scopes.has(scope));
+  const requested = form.get('scope');
+  const scopes =
+    requested === undefined || requested.trim() === ''
+      ? registered
+      : [...new Set(requested.split(' ').filter((scope) => scope !== ''))];
+  if (scopes.length === 0 || !scopes.every((scope) => registered.includes(scope))) {
+    return refused('invalid_scope', 'a requested scope is not one this client was registered for');
+  }
+  const resource = screenResource(config, form.get('resource'));
+  if (resource === false) {
+    return refused('invalid_target', 'the resource is not one this server issues tokens for');
+  }
+  const now = config.clock.now();
+  const grant = {
+    id: `g_${randomToken(16)}`,
+    clientId: client.clientId,
+    subject: client.clientId,
+    scopes,
+    resource,
+    createdAt: now,
+    refreshedAt: now,
+    revokedAt: null,
+  };
+  await config.store.putGrant(grant);
+  // `clientSeconds` is non-null whenever this grant is enabled: the config refuses otherwise.
+  return tokenAnswer(config, grant, config.clientSeconds ?? config.accessSeconds, null);
+}

package/src/grant-device.ts

@@ -0,0 +1,188 @@
+// Single responsibility: RFC 8628 — a CLI on a headless box gets a short user code to type into
+// the app's own verification page while it polls. Both codes are stored hashed; the user code is
+// 8 characters from a no-lookalike alphabet, and every guess at one is counted per caller key.
+// Polling faster than `interval` is `slow_down`; a decision is final and spent exactly once.
+
+import type { ResolvedAuthServerConfig } from './authorization-server-config';
+import { consentInvalid } from './authorization-server-errors';
+import { screenResource, screenScopes } from './authorization-server-request';
+import {
+  firstRefresh,
+  refused,
+  type TokenOutcome,
+  tokenAnswer,
+} from './authorization-server-tokens';
+import type { AuthServerClient } from './authorization-server-types';
+import { DEVICE_GRANT } from './authorization-server-types';
+import { randomBytes, randomToken, sha256Hex } from './tokens';
+
+/** RFC 8628 §6.1's consonant alphabet: no vowels (no words), no 0/O, 1/I/L lookalikes. */
+export const USER_CODE_ALPHABET = 'BCDFGHJKLMNPQRSTVWXZ';
+export const USER_CODE_LENGTH = 8;
+export const DEVICE_INTERVAL_SECONDS = 5;
+
+/** Rejection sampling: `byte % 20` over all 256 values would bias the first 16 letters. */
+export function userCode(): string {
+  let code = '';
+  while (code.length < USER_CODE_LENGTH) {
+    for (const byte of randomBytes(16)) {
+      if (byte >= 240 || code.length === USER_CODE_LENGTH) continue;
+      code += USER_CODE_ALPHABET[byte % USER_CODE_ALPHABET.length];
+    }
+  }
+  return code;
+}
+
+/** What a person types: any case, the dash optional, spaces ignored. */
+export const normaliseUserCode = (typed: string): string =>
+  typed.toUpperCase().replaceAll(/[\s-]/g, '');
+
+export async function startDevice(
+  config: ResolvedAuthServerConfig,
+  form: ReadonlyMap<string, string>,
+  client: AuthServerClient,
+): Promise<TokenOutcome> {
+  if (!client.grantTypes.includes(DEVICE_GRANT)) {
+    return refused('unauthorized_client', 'this client may not use the device grant');
+  }
+  const scopes = screenScopes(config, client, form.get('scope'));
+  if (scopes === null || scopes.length === 0) {
+    return refused('invalid_scope', 'a requested scope is not one this client may be granted');
+  }
+  const resource = screenResource(config, form.get('resource'));
+  if (resource === false) {
+    return refused('invalid_target', 'the resource is not one this server issues tokens for');
+  }
+  const deviceCode = randomToken(32);
+  const user = userCode();
+  const now = config.clock.now();
+  await config.store.putDevice({
+    deviceCodeHash: sha256Hex(deviceCode),
+    userCodeHash: sha256Hex(user),
+    clientId: client.clientId,
+    scopes,
+    resource,
+    status: 'pending',
+    subject: null,
+    grantedScopes: null,
+    intervalSeconds: DEVICE_INTERVAL_SECONDS,
+    lastPolledAt: null,
+    createdAt: now,
+    expiresAt: new Date(now.getTime() + config.deviceSeconds * 1000),
+  });
+  const page = `${config.origin}${config.devicePath ?? ''}`;
+  const shown = `${user.slice(0, 4)}-${user.slice(4)}`;
+  return {
+    ok: true,
+    body: {
+      device_code: deviceCode,
+      user_code: shown,
+      verification_uri: page,
+      verification_uri_complete: `${page}?user_code=${shown}`,
+      expires_in: config.deviceSeconds,
+      interval: DEVICE_INTERVAL_SECONDS,
+    },
+  };
+}
+
+export type DeviceReading =
+  | {
+      readonly ok: true;
+      readonly clientId: string;
+      readonly scopes: readonly string[];
+      readonly resource: string | null;
+    }
+  | { readonly ok: false; readonly reason: 'unknown' | 'expired' | 'decided' };
+
+/**
+ * The verification page's read. `key` is the caller's bucket (address or session): a miss counts
+ * against it, so walking the code space locks the walker out (`X_ACCOUNT_LOCKED`) long before the
+ * 20^8 codes give way. A hit gives its reservation back.
+ */
+export async function readDevice(
+  config: ResolvedAuthServerConfig,
+  typed: string,
+  key: string,
+): Promise<DeviceReading> {
+  const reservation = await config.limiter.reserve(`oauth-device:${key}`);
+  const device = await config.store.deviceByUserCode(sha256Hex(normaliseUserCode(typed)));
+  if (device === null) return { ok: false, reason: 'unknown' };
+  await config.limiter.refund(reservation);
+  if (device.expiresAt.getTime() <= config.clock.now().getTime()) {
+    return { ok: false, reason: 'expired' };
+  }
+  if (device.status !== 'pending') return { ok: false, reason: 'decided' };
+  return { ok: true, clientId: device.clientId, scopes: device.scopes, resource: device.resource };
+}
+
+export async function decideDevice(
+  config: ResolvedAuthServerConfig,
+  input: {
+    readonly userCode: string;
+    readonly key: string;
+    readonly approve: { readonly subject: string; readonly scopes: readonly string[] } | null;
+  },
+): Promise<void> {
+  const reading = await readDevice(config, input.userCode, input.key);
+  if (!reading.ok) throw consentInvalid(`the user code is ${reading.reason}`);
+  const approved = input.approve?.scopes;
+  if (
+    approved !== undefined &&
+    (approved.length === 0 || !approved.every((s) => reading.scopes.includes(s)))
+  ) {
+    throw consentInvalid(
+      'the approved scopes are empty or not a subset of what the device asked for',
+    );
+  }
+  const decided = await config.store.decideDevice(
+    sha256Hex(normaliseUserCode(input.userCode)),
+    input.approve === null
+      ? { status: 'denied' }
+      : { status: 'approved', subject: input.approve.subject, scopes: input.approve.scopes },
+    config.clock.now(),
+  );
+  if (decided === null) throw consentInvalid('the user code was decided or expired meanwhile');
+}
+
+/** The device's poll on `POST /oauth/token`. */
+export async function pollDevice(
+  config: ResolvedAuthServerConfig,
+  form: ReadonlyMap<string, string>,
+  client: AuthServerClient,
+): Promise<TokenOutcome> {
+  const deviceCode = form.get('device_code');
+  if (deviceCode === undefined) return refused('invalid_request', 'device_code is required');
+  const now = config.clock.now();
+  const hash = sha256Hex(deviceCode);
+  const device = await config.store.pollDevice(hash, now);
+  if (device === null || device.clientId !== client.clientId) {
+    return refused('invalid_grant', 'the device code is unknown');
+  }
+  if (device.expiresAt.getTime() <= now.getTime()) {
+    return refused('expired_token', 'the device code expired; start again');
+  }
+  const last = device.lastPolledAt;
+  if (last !== null && now.getTime() - last.getTime() < device.intervalSeconds * 1000) {
+    return refused('slow_down', `poll no faster than every ${device.intervalSeconds} seconds`);
+  }
+  if (device.status === 'pending') return refused('authorization_pending', 'not decided yet');
+  if (device.status === 'denied') return refused('access_denied', 'the person declined');
+  if (device.status === 'consumed' || device.subject === null) {
+    return refused('invalid_grant', 'the device code was already used');
+  }
+  if (!(await config.store.consumeDevice(hash, now))) {
+    return refused('invalid_grant', 'the device code was already used');
+  }
+  const grant = {
+    id: `g_${randomToken(16)}`,
+    clientId: client.clientId,
+    subject: device.subject,
+    scopes: device.grantedScopes ?? [],
+    resource: device.resource,
+    createdAt: now,
+    refreshedAt: now,
+    revokedAt: null,
+  };
+  await config.store.putGrant(grant);
+  return tokenAnswer(config, grant, config.accessSeconds, await firstRefresh(config, grant.id));
+}