@serve.zone/dcrouter 17.2.4 → 17.4.0

package/ts/config/classes.api-token-manager.ts

@@ -3,6 +3,7 @@ import { logger } from '../logger.js';
 import { ApiTokenDoc } from '../db/index.js';
 import type {
   IApiTokenPolicy,
+  IGatewayCredentialLifecycle,
   IStoredApiToken,
   IApiTokenInfo,
   TApiTokenScope,
@@ -11,9 +12,11 @@ import type {
 const TOKEN_PREFIX_STR = 'dcr_';
 const ENV_ADMIN_TOKEN_ID = 'env-admin-token';
 const ENV_ADMIN_TOKEN_CREATED_BY = 'dcrouter-env';
+const LAST_USED_PERSIST_INTERVAL_MS = 60_000;
 
 export class ApiTokenManager {
   private tokens = new Map<string, IStoredApiToken>();
+  private lastUsedPersistedAt = new Map<string, number>();
 
   constructor() {}
 
@@ -38,6 +41,7 @@ export class ApiTokenManager {
     expiresInDays: number | null,
     createdBy: string,
     policy?: IApiTokenPolicy,
+    gatewayCredentialLifecycle: IGatewayCredentialLifecycle | null = null,
   ): Promise<{ id: string; rawToken: string }> {
     const id = plugins.uuid.v4();
     const randomBytes = plugins.crypto.randomBytes(32);
@@ -53,6 +57,7 @@ export class ApiTokenManager {
       tokenHash,
       scopes,
       policy,
+      gatewayCredentialLifecycle: this.normalizeGatewayCredentialLifecycle(gatewayCredentialLifecycle, id),
       createdAt: now,
       expiresAt: expiresInDays != null ? now + expiresInDays * 86400000 : null,
       lastUsedAt: null,
@@ -66,6 +71,33 @@ export class ApiTokenManager {
     return { id, rawToken };
   }
 
+  public async createProvisionedGatewayCredentialCandidate(
+    name: string,
+    scopes: TApiTokenScope[],
+    expiresInDays: number | null,
+    createdBy: string,
+    policy: IApiTokenPolicy,
+    credentialSequence: number,
+    policyDigest: string,
+  ): Promise<{ id: string; rawToken: string }> {
+    if (policy.role !== 'gatewayClient' || !policy.gatewayClient?.id
+      || !Number.isSafeInteger(policy.gatewayClient.policyGeneration)
+      || !Number.isSafeInteger(credentialSequence) || credentialSequence < 1
+      || !/^[a-f0-9]{64}$/.test(policyDigest)) {
+      throw new Error('Provisioned gateway credentials require a bound gateway-client policy');
+    }
+    return await this.createToken(name, scopes, expiresInDays, createdBy, policy, {
+      source: 'provisioned',
+      state: 'candidate',
+      sequence: credentialSequence,
+      policyGeneration: policy.gatewayClient.policyGeneration,
+      policyDigest,
+      finalizedAt: null,
+      cleanupCompletedAt: null,
+      revokedCredentialCount: null,
+    });
+  }
+
   /**
    * Validate a raw token string. Returns the stored token if valid, null otherwise.
    * Also updates lastUsedAt.
@@ -80,9 +112,18 @@ export class ApiTokenManager {
         if (!stored.enabled) return null;
         if (stored.expiresAt !== null && stored.expiresAt < Date.now()) return null;
 
-        // Update lastUsedAt (fire and forget)
-        stored.lastUsedAt = Date.now();
-        this.persistToken(stored).catch(() => {});
+        const now = Date.now();
+        stored.lastUsedAt = now;
+        const persistedAt = this.lastUsedPersistedAt.get(stored.id) || 0;
+        if (now - persistedAt >= LAST_USED_PERSIST_INTERVAL_MS) {
+          this.lastUsedPersistedAt.set(stored.id, now);
+          try {
+            await this.persistToken(stored);
+          } catch (error) {
+            this.lastUsedPersistedAt.set(stored.id, persistedAt);
+            throw error;
+          }
+        }
         return stored;
       }
     }
@@ -146,13 +187,148 @@ export class ApiTokenManager {
   public async revokeToken(id: string): Promise<boolean> {
     if (!this.tokens.has(id)) return false;
     const token = this.tokens.get(id)!;
-    this.tokens.delete(id);
+    // Disable durably before deletion so a failed delete cannot resurrect the
+    // credential after a restart.
+    token.enabled = false;
+    await this.persistToken(token);
     const doc = await ApiTokenDoc.findById(id);
     if (doc) await doc.delete();
+    this.tokens.delete(id);
+    this.lastUsedPersistedAt.delete(id);
     logger.log('info', `API token '${token.name}' revoked (id: ${id})`);
     return true;
   }
 
+  /** Revoke only ordinary gateway-client credentials bound to one live client. */
+  public async revokeGatewayClientCredentials(
+    gatewayClientId: string,
+    excludingTokenId?: string,
+  ): Promise<number> {
+    const ids = Array.from(this.tokens.values())
+      .filter((token) => token.id !== excludingTokenId)
+      .filter((token) => token.id !== ENV_ADMIN_TOKEN_ID)
+      .filter((token) => token.policy?.role === 'gatewayClient')
+      .filter((token) => token.policy?.gatewayClient?.id === gatewayClientId)
+      .map((token) => token.id);
+    let revoked = 0;
+    for (const id of ids) {
+      if (await this.revokeToken(id)) revoked++;
+    }
+    return revoked;
+  }
+
+  /** Revoke only older provisioned credentials during a finalized handover. */
+  public async revokeOlderProvisionedGatewayCredentials(
+    gatewayClientId: string,
+    finalizedSequence: number,
+    excludingTokenId: string,
+  ): Promise<number> {
+    if (!Number.isSafeInteger(finalizedSequence) || finalizedSequence < 1) {
+      throw new Error('Gateway credential finalization sequence is invalid');
+    }
+    const ids = Array.from(this.tokens.values())
+      .filter((token) => token.id !== excludingTokenId)
+      .filter((token) => token.policy?.role === 'gatewayClient')
+      .filter((token) => token.policy?.gatewayClient?.id === gatewayClientId)
+      .filter((token) => token.gatewayCredentialLifecycle?.source === 'provisioned')
+      .filter((token) => Number(token.gatewayCredentialLifecycle?.sequence) < finalizedSequence)
+      .map((token) => token.id);
+    let revoked = 0;
+    for (const id of ids) {
+      if (await this.revokeToken(id)) revoked++;
+    }
+    return revoked;
+  }
+
+  /** Durably activate a provisioned candidate while preserving retry identity. */
+  public async activateProvisionedGatewayCredential(
+    tokenId: string,
+    gatewayClientId: string,
+  ): Promise<{
+    finalizedAt: number;
+    wasAlreadyActive: boolean;
+    lifecycle: IGatewayCredentialLifecycle;
+  }> {
+    const token = this.tokens.get(tokenId);
+    if (!token || token.policy?.role !== 'gatewayClient'
+      || token.policy.gatewayClient?.id !== gatewayClientId) {
+      throw new Error('Provisioned gateway credential is missing or has the wrong owner');
+    }
+    const lifecycle = this.normalizeGatewayCredentialLifecycle(
+      token.gatewayCredentialLifecycle,
+      token.id,
+    );
+    if (!lifecycle) {
+      throw new Error('Manual gateway credentials cannot be finalized');
+    }
+    if (lifecycle.state === 'active') {
+      return {
+        finalizedAt: lifecycle.finalizedAt!,
+        wasAlreadyActive: true,
+        lifecycle,
+      };
+    }
+
+    const previousLifecycle = lifecycle;
+    const finalizedAt = Date.now();
+    token.gatewayCredentialLifecycle = {
+      ...lifecycle,
+      state: 'active',
+      finalizedAt,
+      cleanupCompletedAt: null,
+      revokedCredentialCount: null,
+    };
+    try {
+      await this.persistToken(token);
+    } catch (error) {
+      token.gatewayCredentialLifecycle = previousLifecycle;
+      throw error;
+    }
+    return {
+      finalizedAt,
+      wasAlreadyActive: false,
+      lifecycle: token.gatewayCredentialLifecycle,
+    };
+  }
+
+  /** Mark sibling cleanup complete so later retries never touch newer tokens. */
+  public async completeProvisionedGatewayCredentialHandover(
+    tokenId: string,
+    gatewayClientId: string,
+    revokedCredentialCount: number,
+  ): Promise<IGatewayCredentialLifecycle> {
+    const token = this.tokens.get(tokenId);
+    if (!token || token.policy?.role !== 'gatewayClient'
+      || token.policy.gatewayClient?.id !== gatewayClientId) {
+      throw new Error('Provisioned gateway credential is missing or has the wrong owner');
+    }
+    const lifecycle = this.normalizeGatewayCredentialLifecycle(
+      token.gatewayCredentialLifecycle,
+      token.id,
+    );
+    if (!lifecycle || lifecycle.state !== 'active') {
+      throw new Error('Provisioned gateway credential is not active');
+    }
+    if (lifecycle.cleanupCompletedAt !== null) return lifecycle;
+    if (!Number.isSafeInteger(revokedCredentialCount) || revokedCredentialCount < 0) {
+      throw new Error('Revoked credential count is invalid');
+    }
+    const previousLifecycle = lifecycle;
+    token.gatewayCredentialLifecycle = {
+      ...lifecycle,
+      cleanupCompletedAt: Date.now(),
+      revokedCredentialCount,
+    };
+    try {
+      await this.persistToken(token);
+    } catch (error) {
+      token.gatewayCredentialLifecycle = previousLifecycle;
+      throw error;
+    }
+    return token.gatewayCredentialLifecycle;
+  }
+
+
   /**
    * Roll (regenerate) a token's secret while keeping its identity.
    * Returns the new raw token value (shown once).
@@ -197,12 +373,14 @@ export class ApiTokenManager {
           tokenHash: doc.tokenHash,
           scopes: doc.scopes,
           policy: doc.policy,
+          gatewayCredentialLifecycle: this.normalizeGatewayCredentialLifecycle(doc.gatewayCredentialLifecycle, doc.id),
           createdAt: doc.createdAt,
           expiresAt: doc.expiresAt,
           lastUsedAt: doc.lastUsedAt,
           createdBy: doc.createdBy,
           enabled: doc.enabled,
         });
+        this.lastUsedPersistedAt.set(doc.id, doc.lastUsedAt || 0);
       }
     }
   }
@@ -226,6 +404,7 @@ export class ApiTokenManager {
       tokenHash: this.hashToken(rawToken),
       scopes: ['*'],
       policy: { role: 'admin' },
+      gatewayCredentialLifecycle: null,
       createdAt: existing?.createdAt || now,
       expiresAt: null,
       lastUsedAt: existing?.lastUsedAt || null,
@@ -238,6 +417,58 @@ export class ApiTokenManager {
     logger.log('info', `Environment admin API token ensured (id: ${stored.id})`);
   }
 
+  private normalizeGatewayCredentialLifecycle(
+    valueArg: unknown,
+    tokenIdArg: string,
+  ): IGatewayCredentialLifecycle | null {
+    if (valueArg == null) return null;
+    if (typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+      throw new Error(`API token '${tokenIdArg}' has malformed gateway credential lifecycle`);
+    }
+    const value = valueArg as Partial<IGatewayCredentialLifecycle>;
+    if (value.source !== 'provisioned') {
+      throw new Error(`API token '${tokenIdArg}' has malformed gateway credential lifecycle`);
+    }
+    if (!Number.isSafeInteger(value.sequence) || Number(value.sequence) < 1
+      || !Number.isSafeInteger(value.policyGeneration) || Number(value.policyGeneration) < 1
+      || typeof value.policyDigest !== 'string' || !/^[a-f0-9]{64}$/.test(value.policyDigest)) {
+      throw new Error(`API token '${tokenIdArg}' has malformed gateway credential lifecycle`);
+    }
+    const base = {
+      source: 'provisioned' as const,
+      sequence: Number(value.sequence),
+      policyGeneration: Number(value.policyGeneration),
+      policyDigest: value.policyDigest,
+    };
+    if (value.state === 'candidate' && value.finalizedAt === null
+      && value.cleanupCompletedAt === null && value.revokedCredentialCount === null) {
+      return {
+        ...base,
+        state: 'candidate',
+        finalizedAt: null,
+        cleanupCompletedAt: null,
+        revokedCredentialCount: null,
+      };
+    }
+    if (value.state === 'active' && Number.isSafeInteger(value.finalizedAt) && Number(value.finalizedAt) > 0) {
+      const cleanupPending = value.cleanupCompletedAt === null && value.revokedCredentialCount === null;
+      const cleanupComplete = Number.isSafeInteger(value.cleanupCompletedAt)
+        && Number(value.cleanupCompletedAt) > 0
+        && Number.isSafeInteger(value.revokedCredentialCount)
+        && Number(value.revokedCredentialCount) >= 0;
+      if (cleanupPending || cleanupComplete) {
+        return {
+          ...base,
+          state: 'active',
+          finalizedAt: Number(value.finalizedAt),
+          cleanupCompletedAt: cleanupComplete ? Number(value.cleanupCompletedAt) : null,
+          revokedCredentialCount: cleanupComplete ? Number(value.revokedCredentialCount) : null,
+        };
+      }
+    }
+    throw new Error(`API token '${tokenIdArg}' has malformed gateway credential lifecycle`);
+  }
+
   private hashToken(rawToken: string): string {
     return plugins.crypto.createHash('sha256').update(rawToken).digest('hex');
   }
@@ -249,6 +480,7 @@ export class ApiTokenManager {
       existing.tokenHash = stored.tokenHash;
       existing.scopes = stored.scopes;
       existing.policy = stored.policy;
+      existing.gatewayCredentialLifecycle = stored.gatewayCredentialLifecycle ?? null;
       existing.createdAt = stored.createdAt;
       existing.expiresAt = stored.expiresAt;
       existing.lastUsedAt = stored.lastUsedAt;
@@ -262,6 +494,7 @@ export class ApiTokenManager {
       doc.tokenHash = stored.tokenHash;
       doc.scopes = stored.scopes;
       doc.policy = stored.policy;
+      doc.gatewayCredentialLifecycle = stored.gatewayCredentialLifecycle ?? null;
       doc.createdAt = stored.createdAt;
       doc.expiresAt = stored.expiresAt;
       doc.lastUsedAt = stored.lastUsedAt;