@vellumai/assistant 0.4.6 → 0.4.8

package/src/memory/schema.ts

@@ -1162,6 +1162,25 @@ export const actorTokenRecords = sqliteTable('actor_token_records', {
   updatedAt: integer('updated_at').notNull(),
 });
 
+// ── Actor Refresh Token Records ──────────────────────────────────────
+
+export const actorRefreshTokenRecords = sqliteTable('actor_refresh_token_records', {
+  id: text('id').primaryKey(),
+  tokenHash: text('token_hash').notNull(),
+  familyId: text('family_id').notNull(),
+  assistantId: text('assistant_id').notNull(),
+  guardianPrincipalId: text('guardian_principal_id').notNull(),
+  hashedDeviceId: text('hashed_device_id').notNull(),
+  platform: text('platform').notNull(),
+  status: text('status').notNull().default('active'),
+  issuedAt: integer('issued_at').notNull(),
+  absoluteExpiresAt: integer('absolute_expires_at').notNull(),
+  inactivityExpiresAt: integer('inactivity_expires_at').notNull(),
+  lastUsedAt: integer('last_used_at'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
 // ── Scoped Approval Grants ──────────────────────────────────────────
 
 export const scopedApprovalGrants = sqliteTable('scoped_approval_grants', {

package/src/notifications/README.md

@@ -51,7 +51,14 @@ When the LLM is unavailable or returns invalid output, a deterministic fallback
 
 ### 4. Deterministic Checks
 
-Hard invariants that the LLM cannot override (`deterministic-checks.ts`):
+Hard invariants that the LLM cannot override:
+
+**Post-generation enforcement** (`decision-engine.ts`):
+
+- **Guardian question request-code enforcement** — `enforceGuardianRequestCode()` ensures request-code instructions (approve/reject or free-text answer) appear in all `guardian.question` notification copy, even when the LLM omits them.
+- **Access-request instruction enforcement** — `enforceAccessRequestInstructions()` validates that `ingress.access_request` copy contains: (1) the request-code approve/reject directive, (2) the exact "open invite flow" phrase. If any required element is missing, the full deterministic contract text is appended. This prevents model-generated copy from dropping security-critical action directives.
+
+**Pre-send gate checks** (`deterministic-checks.ts`):
 
 - **Schema validity** -- fail-closed if the decision is malformed
 - **Source-active suppression** -- if the user is already viewing the source context, suppress

package/src/notifications/copy-composer.ts

@@ -29,6 +29,162 @@ export function nonEmpty(value: string | undefined): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
+// ── Access-request copy contract ─────────────────────────────────────────────
+//
+// Deterministic helpers for building guardian-facing access-request copy.
+// These are used both by the fallback template and the decision-engine
+// post-generation enforcement to ensure required directives always appear.
+
+const IDENTITY_FIELD_MAX_LENGTH = 120;
+
+/**
+ * Sanitize an untrusted identity field for inclusion in notification copy.
+ *
+ * - Strips control characters (U+0000–U+001F, U+007F–U+009F) and newlines.
+ * - Clamps to IDENTITY_FIELD_MAX_LENGTH characters.
+ * - Wraps in quotes to neutralize instruction-like payload text.
+ */
+export function sanitizeIdentityField(value: string): string {
+  const stripped = value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, ' ').trim();
+  const clamped = stripped.length > IDENTITY_FIELD_MAX_LENGTH
+    ? stripped.slice(0, IDENTITY_FIELD_MAX_LENGTH) + '…'
+    : stripped;
+  return clamped;
+}
+
+export function buildAccessRequestIdentityLine(payload: Record<string, unknown>): string {
+  const requester = sanitizeIdentityField(str(payload.senderIdentifier, 'Someone'));
+  const sourceChannel = typeof payload.sourceChannel === 'string' ? payload.sourceChannel : undefined;
+  const callerName = nonEmpty(typeof payload.actorDisplayName === 'string' ? payload.actorDisplayName : undefined);
+  const actorUsername = nonEmpty(typeof payload.actorUsername === 'string' ? payload.actorUsername : undefined);
+  const actorExternalId = nonEmpty(typeof payload.actorExternalId === 'string' ? payload.actorExternalId : undefined);
+
+  if (sourceChannel === 'voice' && callerName) {
+    const safeName = sanitizeIdentityField(callerName);
+    const safeId = sanitizeIdentityField(str(payload.actorExternalId, requester));
+    return `${safeName} (${safeId}) is calling and requesting access to the assistant.`;
+  }
+
+  // For non-voice, include extra context when available.
+  // Sanitize before comparing to avoid deduplication failures when identity
+  // fields contain control characters that are stripped from `requester`.
+  const sanitizedUsername = actorUsername ? sanitizeIdentityField(actorUsername) : undefined;
+  const sanitizedExternalId = actorExternalId ? sanitizeIdentityField(actorExternalId) : undefined;
+  const parts = [requester];
+  if (sanitizedUsername && sanitizedUsername !== requester) {
+    parts.push(`@${sanitizedUsername}`);
+  }
+  if (sanitizedExternalId && sanitizedExternalId !== requester && sanitizedExternalId !== sanitizedUsername) {
+    parts.push(`[${sanitizedExternalId}]`);
+  }
+  if (sourceChannel) {
+    parts.push(`via ${sourceChannel}`);
+  }
+
+  return `${parts.join(' ')} is requesting access to the assistant.`;
+}
+
+export function buildAccessRequestDecisionDirective(requestCode: string): string {
+  const code = requestCode.toUpperCase();
+  return `Reply "${code} approve" to grant access or "${code} reject" to deny.`;
+}
+
+export function buildAccessRequestInviteDirective(): string {
+  return 'Reply "open invite flow" to start Trusted Contacts invite flow.';
+}
+
+export function buildAccessRequestRevokedNote(): string {
+  return 'Note: this user was previously revoked.';
+}
+
+/**
+ * Normalize text before running directive-matching regexes.
+ *
+ * - Replaces smart/curly apostrophes (\u2018, \u2019, \u201B) with ASCII `'`
+ *   so contractions like "Don\u2019t" are matched by the `n't` lookbehind.
+ * - Collapses runs of whitespace into a single space so "Do not   reply"
+ *   is matched by the single-space negative lookbehind.
+ * - Trims leading/trailing whitespace.
+ */
+export function normalizeForDirectiveMatching(text: string): string {
+  return text
+    .replace(/[\u2018\u2019\u201B]/g, "'")
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Check whether a text contains the required access-request instruction elements:
+ * 1. Approve directive: Reply "CODE approve"
+ * 2. Reject directive: Reply "CODE reject"
+ * 3. Invite directive: Reply "open invite flow"
+ *
+ * Each directive is matched independently using negative lookbehind to reject
+ * matches preceded by negation words ("not", "n't", "never"). This prevents
+ * contradictory copy like `Do not reply "CODE reject"` from satisfying the
+ * check even when a positive approve directive exists nearby.
+ *
+ * The text is normalized before matching to handle smart apostrophes and
+ * multiple whitespace characters that would otherwise bypass negation detection.
+ */
+export function hasAccessRequestInstructions(
+  text: string | undefined,
+  requestCode: string,
+): boolean {
+  if (typeof text !== 'string') return false;
+  const normalized = normalizeForDirectiveMatching(text);
+  const escapedCode = requestCode.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Each directive must follow "reply" without a preceding negation word.
+  // Negative lookbehinds reject "do not reply", "don't reply", "never reply".
+  const approveRe = new RegExp(
+    `(?<!not\\s)(?<!n't\\s)(?<!never\\s)reply\\b[^.!?\\n]*?"${escapedCode}\\s+approve"`,
+    'i',
+  );
+  const rejectRe = new RegExp(
+    `(?<!not\\s)(?<!n't\\s)(?<!never\\s)reply\\b[^.!?\\n]*?"${escapedCode}\\s+reject"`,
+    'i',
+  );
+  const inviteRe = /(?<!not\s)(?<!n't\s)(?<!never\s)reply\b[^.!?\n]*?"open invite flow"/i;
+
+  return approveRe.test(normalized) && rejectRe.test(normalized) && inviteRe.test(normalized);
+}
+
+/**
+ * Check whether text contains the invite-flow directive ("open invite flow")
+ * using the same normalized negative-lookbehind pattern as the full check.
+ * This is used for enforcement when requestCode is absent but the invite
+ * directive should still be present.
+ */
+export function hasInviteFlowDirective(text: string | undefined): boolean {
+  if (typeof text !== 'string') return false;
+  const normalized = normalizeForDirectiveMatching(text);
+  const inviteRe = /(?<!not\s)(?<!n't\s)(?<!never\s)reply\b[^.!?\n]*?"open invite flow"/i;
+  return inviteRe.test(normalized);
+}
+
+/**
+ * Build the deterministic access-request contract text from payload fields.
+ * This is the canonical baseline that enforcement can append when generated
+ * copy is missing required elements.
+ */
+export function buildAccessRequestContractText(payload: Record<string, unknown>): string {
+  const requestCode = nonEmpty(typeof payload.requestCode === 'string' ? payload.requestCode : undefined);
+  const previousMemberStatus = typeof payload.previousMemberStatus === 'string'
+    ? payload.previousMemberStatus
+    : undefined;
+
+  const lines: string[] = [];
+  lines.push(buildAccessRequestIdentityLine(payload));
+  if (previousMemberStatus === 'revoked') {
+    lines.push(buildAccessRequestRevokedNote());
+  }
+  if (requestCode) {
+    lines.push(buildAccessRequestDecisionDirective(requestCode));
+  }
+  lines.push(buildAccessRequestInviteDirective());
+  return lines.join('\n');
+}
+
 // Templates keyed by dot-separated sourceEventName strings matching producers.
 const TEMPLATES: Record<string, CopyTemplate> = {
   'reminder.fired': (payload) => ({
@@ -60,36 +216,10 @@ const TEMPLATES: Record<string, CopyTemplate> = {
     };
   },
 
-  'ingress.access_request': (payload) => {
-    const requester = str(payload.senderIdentifier, 'Someone');
-    const requestCode = nonEmpty(typeof payload.requestCode === 'string' ? payload.requestCode : undefined);
-    const sourceChannel = typeof payload.sourceChannel === 'string' ? payload.sourceChannel : undefined;
-    const callerName = nonEmpty(typeof payload.actorDisplayName === 'string' ? payload.actorDisplayName : undefined);
-    const previousMemberStatus = typeof payload.previousMemberStatus === 'string'
-      ? payload.previousMemberStatus
-      : undefined;
-    const lines: string[] = [];
-
-    // Voice-originated access requests include caller name context
-    if (sourceChannel === 'voice' && callerName) {
-      lines.push(`${callerName} (${str(payload.actorExternalId, requester)}) is calling and requesting access to the assistant.`);
-    } else {
-      lines.push(`${requester} is requesting access to the assistant.`);
-    }
-    if (previousMemberStatus === 'revoked') {
-      lines.push('Note: this user was previously revoked.');
-    }
-
-    if (requestCode) {
-      const code = requestCode.toUpperCase();
-      lines.push(`Reply "${code} approve" to grant access or "${code} reject" to deny.`);
-    }
-    lines.push('Reply "open invite flow" to start Trusted Contacts invite flow.');
-    return {
-      title: 'Access Request',
-      body: lines.join('\n'),
-    };
-  },
+  'ingress.access_request': (payload) => ({
+    title: 'Access Request',
+    body: buildAccessRequestContractText(payload),
+  }),
 
   'ingress.access_request.callback_handoff': (payload) => {
     const callerName = nonEmpty(typeof payload.callerName === 'string' ? payload.callerName : undefined);

package/src/notifications/decision-engine.ts

@@ -16,7 +16,13 @@ import { getConfig } from '../config/loader.js';
 import { createTimeout, extractToolUse, getConfiguredProvider, userMessage } from '../providers/provider-send-message.js';
 import type { ModelIntent } from '../providers/types.js';
 import { getLogger } from '../util/logger.js';
-import { composeFallbackCopy } from './copy-composer.js';
+import {
+  buildAccessRequestContractText,
+  buildAccessRequestInviteDirective,
+  composeFallbackCopy,
+  hasAccessRequestInstructions,
+  hasInviteFlowDirective,
+} from './copy-composer.js';
 import { createDecision } from './decisions-store.js';
 import {
   buildGuardianRequestCodeInstruction,
@@ -474,6 +480,95 @@ function enforceGuardianRequestCode(
   };
 }
 
+/**
+ * Access-request notifications require deterministic instruction elements:
+ * - Request-code approve/reject directive (when requestCode is present)
+ * - Exact "open invite flow" phrase (always required)
+ *
+ * When requestCode IS present: use the full hasAccessRequestInstructions
+ * check (approve+reject+invite) and append the complete contract text if
+ * any element is missing.
+ *
+ * When requestCode is NOT present: still check for the invite-flow
+ * directive and append it if missing. Per the documented contract, the
+ * invite directive should always be present in access-request copy.
+ */
+function enforceAccessRequestInstructions(
+  decision: NotificationDecision,
+  signal: NotificationSignal,
+): NotificationDecision {
+  if (signal.sourceEventName !== 'ingress.access_request') return decision;
+
+  const rawCode = signal.contextPayload.requestCode;
+  const hasRequestCode = typeof rawCode === 'string' && rawCode.trim().length > 0;
+
+  const nextCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {
+    ...decision.renderedCopy,
+  };
+
+  if (hasRequestCode) {
+    const requestCode = rawCode.trim().toUpperCase();
+    const contractText = buildAccessRequestContractText(signal.contextPayload);
+
+    for (const channel of Object.keys(nextCopy) as NotificationChannel[]) {
+      const copy = nextCopy[channel];
+      if (!copy) continue;
+      nextCopy[channel] = ensureAccessRequestInstructionsInCopy(copy, requestCode, contractText);
+    }
+  } else {
+    // No requestCode — still enforce the invite-flow directive.
+    const inviteDirective = buildAccessRequestInviteDirective();
+
+    for (const channel of Object.keys(nextCopy) as NotificationChannel[]) {
+      const copy = nextCopy[channel];
+      if (!copy) continue;
+      nextCopy[channel] = ensureInviteFlowDirectiveInCopy(copy, inviteDirective);
+    }
+  }
+
+  return {
+    ...decision,
+    renderedCopy: nextCopy,
+  };
+}
+
+function ensureAccessRequestInstructionsInCopy(
+  copy: RenderedChannelCopy,
+  requestCode: string,
+  contractText: string,
+): RenderedChannelCopy {
+  const ensureText = (text: string | undefined): string => {
+    const base = typeof text === 'string' ? text.trim() : '';
+    if (hasAccessRequestInstructions(base, requestCode)) return base;
+    return base.length > 0 ? `${base}\n\n${contractText}` : contractText;
+  };
+
+  return {
+    ...copy,
+    body: ensureText(copy.body),
+    deliveryText: copy.deliveryText ? ensureText(copy.deliveryText) : copy.deliveryText,
+    threadSeedMessage: copy.threadSeedMessage ? ensureText(copy.threadSeedMessage) : copy.threadSeedMessage,
+  };
+}
+
+function ensureInviteFlowDirectiveInCopy(
+  copy: RenderedChannelCopy,
+  inviteDirective: string,
+): RenderedChannelCopy {
+  const ensureText = (text: string | undefined): string => {
+    const base = typeof text === 'string' ? text.trim() : '';
+    if (hasInviteFlowDirective(base)) return base;
+    return base.length > 0 ? `${base}\n\n${inviteDirective}` : inviteDirective;
+  };
+
+  return {
+    ...copy,
+    body: ensureText(copy.body),
+    deliveryText: copy.deliveryText ? ensureText(copy.deliveryText) : copy.deliveryText,
+    threadSeedMessage: copy.threadSeedMessage ? ensureText(copy.threadSeedMessage) : copy.threadSeedMessage,
+  };
+}
+
 // ── Core evaluation function ───────────────────────────────────────────
 
 export async function evaluateSignal(
@@ -513,6 +608,7 @@ export async function evaluateSignal(
     log.warn('Configured provider unavailable for notification decision, using fallback');
     let decision = buildFallbackDecision(signal, availableChannels);
     decision = enforceGuardianRequestCode(decision, signal);
+    decision = enforceAccessRequestInstructions(decision, signal);
     decision = enforceConversationAffinity(decision, signal.conversationAffinityHint);
     decision.persistedDecisionId = persistDecision(signal, decision);
     return decision;
@@ -528,6 +624,7 @@ export async function evaluateSignal(
   }
 
   decision = enforceGuardianRequestCode(decision, signal);
+  decision = enforceAccessRequestInstructions(decision, signal);
   decision = enforceConversationAffinity(decision, signal.conversationAffinityHint);
   decision.persistedDecisionId = persistDecision(signal, decision);
 

package/src/runtime/actor-refresh-token-service.ts

@@ -0,0 +1,309 @@
+/**
+ * Refresh token service — mint, rotate, and validate refresh tokens.
+ *
+ * Implements rotating single-use refresh tokens with:
+ * - Absolute expiry (365 days)
+ * - Inactivity expiry (90 days since last refresh)
+ * - Replay detection (reuse of rotated token revokes entire family)
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+
+import { getDb } from '../memory/db.js';
+import { getLogger } from '../util/logger.js';
+import {
+  createRefreshTokenRecord,
+  findByTokenHash as findRefreshByHash,
+  markRotated,
+  revokeByDeviceBinding as revokeRefreshTokensByDevice,
+  revokeFamily,
+} from './actor-refresh-token-store.js';
+import { hashToken, mintActorToken } from './actor-token-service.js';
+import {
+  createActorTokenRecord,
+  revokeByDeviceBinding as revokeActorTokensByDevice,
+} from './actor-token-store.js';
+
+const log = getLogger('actor-refresh-token-service');
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Access token TTL: 30 days (reduced from 90). */
+const ACCESS_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Refresh token absolute expiry: 365 days from issuance. */
+const REFRESH_ABSOLUTE_TTL_MS = 365 * 24 * 60 * 60 * 1000;
+
+/** Refresh token inactivity expiry: 90 days since last successful refresh. */
+const REFRESH_INACTIVITY_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+
+/** Proactive refresh hint: suggest refreshing when 80% of access token TTL has elapsed. */
+const REFRESH_AFTER_FRACTION = 0.8;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type RefreshErrorCode =
+  | 'refresh_invalid'
+  | 'refresh_expired'
+  | 'refresh_reuse_detected'
+  | 'device_binding_mismatch'
+  | 'revoked';
+
+export interface RefreshResult {
+  guardianPrincipalId: string;
+  actorToken: string;
+  actorTokenExpiresAt: number;
+  refreshToken: string;
+  refreshTokenExpiresAt: number;
+  refreshAfter: number;
+}
+
+export interface MintRefreshTokenResult {
+  refreshToken: string;
+  refreshTokenHash: string;
+  refreshTokenExpiresAt: number;
+  refreshAfter: number;
+}
+
+// ---------------------------------------------------------------------------
+// Mint a fresh refresh token (used by bootstrap/pairing)
+// ---------------------------------------------------------------------------
+
+/** Hash a raw refresh token for storage. Reuses the actor-token hash function. */
+function hashRefreshToken(token: string): string {
+  return hashToken(token);
+}
+
+/** Generate a cryptographically random refresh token. */
+function generateRefreshToken(): string {
+  return randomBytes(32).toString('base64url');
+}
+
+/**
+ * Mint a new refresh token and persist its hash.
+ * Called during bootstrap, pairing, and rotation.
+ */
+export function mintRefreshToken(params: {
+  assistantId: string;
+  guardianPrincipalId: string;
+  hashedDeviceId: string;
+  platform: string;
+  familyId?: string;
+  /** When provided (during rotation), inherit the parent token's absolute expiry
+   *  instead of computing a fresh one. This ensures refresh rotation resets the
+   *  inactivity window but does NOT extend the absolute session lifetime. */
+  absoluteExpiresAt?: number;
+}): MintRefreshTokenResult {
+  const now = Date.now();
+  const familyId = params.familyId ?? randomBytes(16).toString('hex');
+  const refreshToken = generateRefreshToken();
+  const refreshTokenHash = hashRefreshToken(refreshToken);
+  const absoluteExpiresAt = params.absoluteExpiresAt ?? now + REFRESH_ABSOLUTE_TTL_MS;
+  const inactivityExpiresAt = now + REFRESH_INACTIVITY_TTL_MS;
+
+  createRefreshTokenRecord({
+    tokenHash: refreshTokenHash,
+    familyId,
+    assistantId: params.assistantId,
+    guardianPrincipalId: params.guardianPrincipalId,
+    hashedDeviceId: params.hashedDeviceId,
+    platform: params.platform,
+    issuedAt: now,
+    absoluteExpiresAt,
+    inactivityExpiresAt,
+  });
+
+  return {
+    refreshToken,
+    refreshTokenHash,
+    refreshTokenExpiresAt: Math.min(absoluteExpiresAt, inactivityExpiresAt),
+    refreshAfter: now + Math.floor(ACCESS_TOKEN_TTL_MS * REFRESH_AFTER_FRACTION),
+  };
+}
+
+/**
+ * Mint both an access token and a refresh token for initial credential issuance.
+ * Used by bootstrap and pairing flows.
+ */
+export function mintCredentialPair(params: {
+  assistantId: string;
+  platform: string;
+  deviceId: string;
+  guardianPrincipalId: string;
+  hashedDeviceId: string;
+}): {
+  actorToken: string;
+  actorTokenExpiresAt: number;
+  refreshToken: string;
+  refreshTokenExpiresAt: number;
+  refreshAfter: number;
+  guardianPrincipalId: string;
+} {
+  // Revoke any existing credentials for this device
+  revokeActorTokensByDevice(params.assistantId, params.guardianPrincipalId, params.hashedDeviceId);
+  revokeRefreshTokensByDevice(params.assistantId, params.guardianPrincipalId, params.hashedDeviceId);
+
+  // Mint new access token with 30-day TTL
+  const { token: actorToken, tokenHash: actorTokenHash, claims } = mintActorToken({
+    assistantId: params.assistantId,
+    platform: params.platform,
+    deviceId: params.deviceId,
+    guardianPrincipalId: params.guardianPrincipalId,
+    ttlMs: ACCESS_TOKEN_TTL_MS,
+  });
+
+  createActorTokenRecord({
+    tokenHash: actorTokenHash,
+    assistantId: params.assistantId,
+    guardianPrincipalId: params.guardianPrincipalId,
+    hashedDeviceId: params.hashedDeviceId,
+    platform: params.platform,
+    issuedAt: claims.iat,
+    expiresAt: claims.exp,
+  });
+
+  // Mint new refresh token
+  const refresh = mintRefreshToken({
+    assistantId: params.assistantId,
+    guardianPrincipalId: params.guardianPrincipalId,
+    hashedDeviceId: params.hashedDeviceId,
+    platform: params.platform,
+  });
+
+  return {
+    actorToken,
+    actorTokenExpiresAt: claims.exp!,
+    refreshToken: refresh.refreshToken,
+    refreshTokenExpiresAt: refresh.refreshTokenExpiresAt,
+    refreshAfter: refresh.refreshAfter,
+    guardianPrincipalId: params.guardianPrincipalId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Rotate (the core refresh operation)
+// ---------------------------------------------------------------------------
+
+/**
+ * Rotate credentials: validate refresh token, revoke old, mint new pair.
+ *
+ * Returns either a successful result or an error code.
+ */
+export function rotateCredentials(params: {
+  refreshToken: string;
+  platform: string;
+  deviceId: string;
+}): { ok: true; result: RefreshResult } | { ok: false; error: RefreshErrorCode } {
+  const refreshTokenHash = hashRefreshToken(params.refreshToken);
+  const hashedDeviceId = createHash('sha256').update(params.deviceId).digest('hex');
+
+  // Look up the refresh token by hash (any status)
+  const record = findRefreshByHash(refreshTokenHash);
+
+  if (!record) {
+    return { ok: false, error: 'refresh_invalid' };
+  }
+
+  // Check if this is a reuse of an already-rotated token (replay detection)
+  if (record.status === 'rotated') {
+    log.warn(
+      { familyId: record.familyId, hashedDeviceId: record.hashedDeviceId },
+      'Refresh token reuse detected — revoking entire family',
+    );
+    revokeFamily(record.familyId);
+    revokeActorTokensByDevice(record.assistantId, record.guardianPrincipalId, record.hashedDeviceId);
+    return { ok: false, error: 'refresh_reuse_detected' };
+  }
+
+  if (record.status === 'revoked') {
+    return { ok: false, error: 'revoked' };
+  }
+
+  // At this point status === 'active'
+  const now = Date.now();
+
+  // Check absolute expiry
+  if (now > record.absoluteExpiresAt) {
+    return { ok: false, error: 'refresh_expired' };
+  }
+
+  // Check inactivity expiry
+  if (now > record.inactivityExpiresAt) {
+    return { ok: false, error: 'refresh_expired' };
+  }
+
+  // Verify device binding
+  if (record.hashedDeviceId !== hashedDeviceId) {
+    return { ok: false, error: 'device_binding_mismatch' };
+  }
+
+  if (record.platform !== params.platform) {
+    return { ok: false, error: 'device_binding_mismatch' };
+  }
+
+  // Wrap the entire rotate-revoke-remint sequence in a transaction so that
+  // partial failures (e.g., DB write error after revoking old tokens) roll back
+  // atomically instead of stranding device credentials.
+  const db = getDb();
+  return db.transaction(() => {
+    // Mark old refresh token as rotated (atomic CAS — fails if a concurrent request already consumed it)
+    const didRotate = markRotated(refreshTokenHash);
+    if (!didRotate) {
+      return { ok: false as const, error: 'refresh_reuse_detected' as const };
+    }
+
+    // Revoke old access tokens for this device
+    revokeActorTokensByDevice(record.assistantId, record.guardianPrincipalId, record.hashedDeviceId);
+
+    // Mint new access token
+    const { token: actorToken, tokenHash: actorTokenHash, claims } = mintActorToken({
+      assistantId: record.assistantId,
+      platform: params.platform,
+      deviceId: params.deviceId,
+      guardianPrincipalId: record.guardianPrincipalId,
+      ttlMs: ACCESS_TOKEN_TTL_MS,
+    });
+
+    createActorTokenRecord({
+      tokenHash: actorTokenHash,
+      assistantId: record.assistantId,
+      guardianPrincipalId: record.guardianPrincipalId,
+      hashedDeviceId: record.hashedDeviceId,
+      platform: params.platform,
+      issuedAt: claims.iat,
+      expiresAt: claims.exp,
+    });
+
+    // Mint new refresh token in the same family, inheriting the parent's absolute
+    // expiry so rotation resets inactivity but never extends the session lifetime.
+    const refresh = mintRefreshToken({
+      assistantId: record.assistantId,
+      guardianPrincipalId: record.guardianPrincipalId,
+      hashedDeviceId: record.hashedDeviceId,
+      platform: params.platform,
+      familyId: record.familyId,
+      absoluteExpiresAt: record.absoluteExpiresAt,
+    });
+
+    log.info(
+      { familyId: record.familyId, platform: params.platform },
+      'Credential rotation completed',
+    );
+
+    return {
+      ok: true as const,
+      result: {
+        guardianPrincipalId: record.guardianPrincipalId,
+        actorToken,
+        actorTokenExpiresAt: claims.exp!,
+        refreshToken: refresh.refreshToken,
+        refreshTokenExpiresAt: refresh.refreshTokenExpiresAt,
+        refreshAfter: refresh.refreshAfter,
+      },
+    };
+  });
+}