@undefineds.co/xpod 0.3.58 → 0.3.61

package/dist/api/ai-gateway/auth/GatewayApiKeyAuthenticator.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayApiKeyAuthenticator = exports.DEFAULT_GATEWAY_API_KEY_SCOPES = void 0;
+const node_crypto_1 = require("node:crypto");
+const GatewayApiKey_1 = require("./GatewayApiKey");
+const InvocationTokenCodec_1 = require("./InvocationTokenCodec");
+const INVALID_GATEWAY_API_KEY = 'Invalid gateway API key';
+exports.DEFAULT_GATEWAY_API_KEY_SCOPES = ['models:read', 'inference:write'];
+class GatewayApiKeyAuthenticator {
+    constructor(options) {
+        this.repository = options.repository;
+        this.deployment = options.deployment;
+        this.requiredScopes = options.requiredScopes ?? [...exports.DEFAULT_GATEWAY_API_KEY_SCOPES];
+        this.invocationTokenCodec = options.invocationTokenCodec;
+        this.invocationTokenAudience = options.invocationTokenAudience
+            ? (0, InvocationTokenCodec_1.requireCanonicalOrigin)(options.invocationTokenAudience, 'audience')
+            : undefined;
+        this.invocationTokenIssuer = options.invocationTokenIssuer
+            ? (0, InvocationTokenCodec_1.requireCanonicalOrigin)(options.invocationTokenIssuer, 'issuer')
+            : this.invocationTokenAudience;
+        this.now = options.now ?? (() => new Date());
+        this.maxClockSkewMs = options.maxClockSkewMs ?? 5_000;
+        if (!Number.isSafeInteger(this.maxClockSkewMs) || this.maxClockSkewMs < 0 || this.maxClockSkewMs > 30_000) {
+            throw new Error('Gateway invocation token clock skew must be between 0 and 30000 milliseconds');
+        }
+        this.dummyHash = (0, GatewayApiKey_1.hashGatewayApiKeySecret)('xpod-gateway-missing-key-dummy-secret');
+    }
+    canAuthenticate(request) {
+        const bearer = this.readBearer(request);
+        return Boolean(bearer
+            && (bearer.startsWith('xpod_inv_v1.') || (0, GatewayApiKey_1.parseGatewayApiKey)(bearer)));
+    }
+    async authenticate(request) {
+        const bearer = this.readBearer(request);
+        if (bearer?.startsWith('xpod_inv_v1.')) {
+            return this.authenticateInvocationToken(bearer);
+        }
+        const parsed = bearer ? (0, GatewayApiKey_1.parseGatewayApiKey)(bearer) : undefined;
+        if (!parsed) {
+            return { success: false, error: INVALID_GATEWAY_API_KEY };
+        }
+        let record;
+        try {
+            record = await this.repository.findById(parsed.keyId);
+        }
+        catch (cause) {
+            return infrastructureError(cause);
+        }
+        if (!record) {
+            await (0, GatewayApiKey_1.verifyGatewayApiKeySecret)(parsed.secret, await this.dummyHash);
+            return invalidGatewayApiKey();
+        }
+        const secretMatches = await (0, GatewayApiKey_1.verifyGatewayApiKeySecret)(parsed.secret, record.secretHash);
+        if (!secretMatches
+            || parsed.deployment !== this.deployment
+            || record.deployment !== this.deployment
+            || record.revokedAt
+            || isExpired(record, this.now())
+            || !hasRequiredScopes(record.scopes, this.requiredScopes)) {
+            return invalidGatewayApiKey();
+        }
+        const lastUsedAt = this.now();
+        try {
+            await this.repository.touchLastUsed(record.id, lastUsedAt);
+        }
+        catch (cause) {
+            return infrastructureError(cause);
+        }
+        const context = {
+            type: 'solid',
+            webId: record.owner,
+            accountId: record.owner,
+            viaGatewayApiKey: true,
+            gatewayKeyId: record.id,
+            gatewayKeyFingerprint: fingerprintGatewayBearer(bearer),
+            scopes: record.scopes,
+            tokenType: 'Bearer',
+        };
+        return { success: true, context };
+    }
+    authenticateInvocationToken(token) {
+        const claims = this.invocationTokenCodec?.decode(token);
+        if (!claims || !this.validInvocationClaims(claims)) {
+            return invalidGatewayApiKey();
+        }
+        const context = {
+            type: 'solid',
+            webId: claims.webId,
+            accountId: claims.webId,
+            viaGatewayApiKey: true,
+            internalInvocation: true,
+            gatewayKeyId: claims.jti,
+            gatewayKeyFingerprint: fingerprintGatewayBearer(token),
+            scopes: claims.scopes,
+            tokenType: 'Bearer',
+        };
+        return { success: true, context };
+    }
+    validInvocationClaims(claims) {
+        const now = this.now().getTime();
+        return (claims.deployment === this.deployment
+            && (!this.invocationTokenAudience || claims.audience === this.invocationTokenAudience)
+            && (!this.invocationTokenIssuer || claims.issuer === this.invocationTokenIssuer)
+            && claims.issuedAt.getTime() <= now + this.maxClockSkewMs
+            && claims.expiresAt.getTime() > now
+            && hasRequiredScopes(claims.scopes, this.requiredScopes));
+    }
+    readBearer(request) {
+        const authorization = request.headers.authorization;
+        if (!authorization?.startsWith('Bearer ')) {
+            return undefined;
+        }
+        return authorization.slice(7).trim();
+    }
+}
+exports.GatewayApiKeyAuthenticator = GatewayApiKeyAuthenticator;
+function fingerprintGatewayBearer(bearer) {
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(bearer).digest('hex')}`;
+}
+function invalidGatewayApiKey() {
+    return {
+        success: false,
+        error: INVALID_GATEWAY_API_KEY,
+        category: 'invalid_credentials',
+        statusCode: 401,
+    };
+}
+function infrastructureError(cause) {
+    return {
+        success: false,
+        error: 'Gateway API key authentication unavailable',
+        category: 'service_unavailable',
+        statusCode: 503,
+        cause,
+    };
+}
+function isExpired(record, now) {
+    return Boolean(record.expiresAt && record.expiresAt.getTime() <= now.getTime());
+}
+function hasRequiredScopes(scopes, requiredScopes) {
+    return requiredScopes.every((scope) => scopes.includes(scope));
+}
+//# sourceMappingURL=GatewayApiKeyAuthenticator.js.map

package/dist/api/ai-gateway/auth/GatewayApiKeyAuthenticator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GatewayApiKeyAuthenticator.js","sourceRoot":"","sources":["../../../../src/api/ai-gateway/auth/GatewayApiKeyAuthenticator.ts"],"names":[],"mappings":"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","sourcesContent":["import type { IncomingMessage } from 'node:http';\nimport { createHash } from 'node:crypto';\nimport type { Authenticator, AuthResult } from '../../auth/Authenticator';\nimport type { AuthContext, SolidAuthContext } from '../../auth/AuthContext';\nimport {\n  type GatewayDeployment,\n  hashGatewayApiKeySecret,\n  parseGatewayApiKey,\n  verifyGatewayApiKeySecret,\n} from './GatewayApiKey';\nimport type { InvocationTokenClaims, InvocationTokenCodec } from './InvocationTokenCodec';\nimport { requireCanonicalOrigin } from './InvocationTokenCodec';\n\nexport interface GatewayAccessKeyRecord {\n  id: string;\n  owner: string;\n  secretHash: string;\n  deployment: GatewayDeployment;\n  scopes: string[];\n  createdAt: Date;\n  expiresAt?: Date;\n  lastUsedAt?: Date;\n  revokedAt?: Date;\n  name?: string;\n}\n\nexport interface GatewayAccessKeyRepositoryContext {\n  auth?: AuthContext;\n}\n\nexport interface GatewayAccessKeyRepository {\n  createKeyId?(owner: string, deployment: GatewayDeployment): string;\n  create(record: GatewayAccessKeyRecord, context?: GatewayAccessKeyRepositoryContext): Promise<GatewayAccessKeyRecord>;\n  findById(id: string): Promise<GatewayAccessKeyRecord | undefined>;\n  listByOwner(owner: string, context?: GatewayAccessKeyRepositoryContext): Promise<GatewayAccessKeyRecord[]>;\n  revoke(id: string, revokedAt: Date, context?: GatewayAccessKeyRepositoryContext): Promise<GatewayAccessKeyRecord | undefined>;\n  touchLastUsed(id: string, lastUsedAt: Date): Promise<void>;\n}\n\nexport interface GatewayApiKeyAuthenticatorOptions {\n  repository: GatewayAccessKeyRepository;\n  deployment: GatewayDeployment;\n  requiredScopes?: string[];\n  invocationTokenCodec?: InvocationTokenCodec;\n  invocationTokenAudience?: string;\n  invocationTokenIssuer?: string;\n  now?: () => Date;\n  maxClockSkewMs?: number;\n}\n\nconst INVALID_GATEWAY_API_KEY = 'Invalid gateway API key';\nexport const DEFAULT_GATEWAY_API_KEY_SCOPES = ['models:read', 'inference:write'] as const;\n\nexport class GatewayApiKeyAuthenticator implements Authenticator {\n  private readonly repository: GatewayAccessKeyRepository;\n  private readonly deployment: GatewayDeployment;\n  private readonly requiredScopes: string[];\n  private readonly invocationTokenCodec?: InvocationTokenCodec;\n  private readonly invocationTokenAudience?: string;\n  private readonly invocationTokenIssuer?: string;\n  private readonly now: () => Date;\n  private readonly maxClockSkewMs: number;\n  private readonly dummyHash: Promise<string>;\n\n  public constructor(options: GatewayApiKeyAuthenticatorOptions) {\n    this.repository = options.repository;\n    this.deployment = options.deployment;\n    this.requiredScopes = options.requiredScopes ?? [...DEFAULT_GATEWAY_API_KEY_SCOPES];\n    this.invocationTokenCodec = options.invocationTokenCodec;\n    this.invocationTokenAudience = options.invocationTokenAudience\n      ? requireCanonicalOrigin(options.invocationTokenAudience, 'audience')\n      : undefined;\n    this.invocationTokenIssuer = options.invocationTokenIssuer\n      ? requireCanonicalOrigin(options.invocationTokenIssuer, 'issuer')\n      : this.invocationTokenAudience;\n    this.now = options.now ?? (() => new Date());\n    this.maxClockSkewMs = options.maxClockSkewMs ?? 5_000;\n    if (!Number.isSafeInteger(this.maxClockSkewMs) || this.maxClockSkewMs < 0 || this.maxClockSkewMs > 30_000) {\n      throw new Error('Gateway invocation token clock skew must be between 0 and 30000 milliseconds');\n    }\n    this.dummyHash = hashGatewayApiKeySecret('xpod-gateway-missing-key-dummy-secret');\n  }\n\n  public canAuthenticate(request: IncomingMessage): boolean {\n    const bearer = this.readBearer(request);\n    return Boolean(\n      bearer\n      && (bearer.startsWith('xpod_inv_v1.') || parseGatewayApiKey(bearer)),\n    );\n  }\n\n  public async authenticate(request: IncomingMessage): Promise<AuthResult> {\n    const bearer = this.readBearer(request);\n    if (bearer?.startsWith('xpod_inv_v1.')) {\n      return this.authenticateInvocationToken(bearer);\n    }\n    const parsed = bearer ? parseGatewayApiKey(bearer) : undefined;\n    if (!parsed) {\n      return { success: false, error: INVALID_GATEWAY_API_KEY };\n    }\n\n    let record: GatewayAccessKeyRecord | undefined;\n    try {\n      record = await this.repository.findById(parsed.keyId);\n    } catch (cause) {\n      return infrastructureError(cause);\n    }\n    if (!record) {\n      await verifyGatewayApiKeySecret(parsed.secret, await this.dummyHash);\n      return invalidGatewayApiKey();\n    }\n\n    const secretMatches = await verifyGatewayApiKeySecret(parsed.secret, record.secretHash);\n    if (\n      !secretMatches\n      || parsed.deployment !== this.deployment\n      || record.deployment !== this.deployment\n      || record.revokedAt\n      || isExpired(record, this.now())\n      || !hasRequiredScopes(record.scopes, this.requiredScopes)\n    ) {\n      return invalidGatewayApiKey();\n    }\n\n    const lastUsedAt = this.now();\n    try {\n      await this.repository.touchLastUsed(record.id, lastUsedAt);\n    } catch (cause) {\n      return infrastructureError(cause);\n    }\n\n    const context: SolidAuthContext = {\n      type: 'solid',\n      webId: record.owner,\n      accountId: record.owner,\n      viaGatewayApiKey: true,\n      gatewayKeyId: record.id,\n      gatewayKeyFingerprint: fingerprintGatewayBearer(bearer!),\n      scopes: record.scopes,\n      tokenType: 'Bearer',\n    };\n    return { success: true, context };\n  }\n\n  private authenticateInvocationToken(token: string): AuthResult {\n    const claims = this.invocationTokenCodec?.decode(token);\n    if (!claims || !this.validInvocationClaims(claims)) {\n      return invalidGatewayApiKey();\n    }\n    const context: SolidAuthContext = {\n      type: 'solid',\n      webId: claims.webId,\n      accountId: claims.webId,\n      viaGatewayApiKey: true,\n      internalInvocation: true,\n      gatewayKeyId: claims.jti,\n      gatewayKeyFingerprint: fingerprintGatewayBearer(token),\n      scopes: claims.scopes,\n      tokenType: 'Bearer',\n    };\n    return { success: true, context };\n  }\n\n  private validInvocationClaims(claims: InvocationTokenClaims): boolean {\n    const now = this.now().getTime();\n    return (\n      claims.deployment === this.deployment\n      && (!this.invocationTokenAudience || claims.audience === this.invocationTokenAudience)\n      && (!this.invocationTokenIssuer || claims.issuer === this.invocationTokenIssuer)\n      && claims.issuedAt.getTime() <= now + this.maxClockSkewMs\n      && claims.expiresAt.getTime() > now\n      && hasRequiredScopes(claims.scopes, this.requiredScopes)\n    );\n  }\n\n  private readBearer(request: IncomingMessage): string | undefined {\n    const authorization = request.headers.authorization;\n    if (!authorization?.startsWith('Bearer ')) {\n      return undefined;\n    }\n    return authorization.slice(7).trim();\n  }\n}\n\nfunction fingerprintGatewayBearer(bearer: string): string {\n  return `sha256:${createHash('sha256').update(bearer).digest('hex')}`;\n}\n\nfunction invalidGatewayApiKey(): AuthResult {\n  return {\n    success: false,\n    error: INVALID_GATEWAY_API_KEY,\n    category: 'invalid_credentials',\n    statusCode: 401,\n  };\n}\n\nfunction infrastructureError(cause: unknown): AuthResult {\n  return {\n    success: false,\n    error: 'Gateway API key authentication unavailable',\n    category: 'service_unavailable',\n    statusCode: 503,\n    cause,\n  };\n}\n\nfunction isExpired(record: GatewayAccessKeyRecord, now: Date): boolean {\n  return Boolean(record.expiresAt && record.expiresAt.getTime() <= now.getTime());\n}\n\nfunction hasRequiredScopes(scopes: string[], requiredScopes: string[]): boolean {\n  return requiredScopes.every((scope) => scopes.includes(scope));\n}\n"]}

package/dist/api/ai-gateway/auth/GatewayKeyLocatorCodec.d.ts

@@ -0,0 +1,26 @@
+import type { GatewayDeployment } from './GatewayApiKey';
+export interface GatewayKeyLocatorPayload {
+    owner: string;
+    keyId: string;
+    deployment: GatewayDeployment;
+}
+export interface GatewayKeyLocatorCodec {
+    encode(payload: GatewayKeyLocatorPayload): string;
+    decode(locator: string): GatewayKeyLocatorPayload | undefined;
+}
+export interface GatewayKeyLocatorSecret {
+    kid: string;
+    secret: string;
+}
+export interface AesGatewayKeyLocatorCodecOptions {
+    active: GatewayKeyLocatorSecret;
+    previous?: GatewayKeyLocatorSecret[];
+}
+export declare class AesGatewayKeyLocatorCodec implements GatewayKeyLocatorCodec {
+    private readonly active;
+    private readonly ring;
+    constructor(secretOrOptions: string | AesGatewayKeyLocatorCodecOptions);
+    encode(payload: GatewayKeyLocatorPayload): string;
+    decode(locator: string): GatewayKeyLocatorPayload | undefined;
+}
+export declare function createGatewayKeyLocator(owner: string, deployment: GatewayDeployment, codec: GatewayKeyLocatorCodec): string;

package/dist/api/ai-gateway/auth/GatewayKeyLocatorCodec.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AesGatewayKeyLocatorCodec = void 0;
+exports.createGatewayKeyLocator = createGatewayKeyLocator;
+const node_crypto_1 = require("node:crypto");
+const PREFIX = 'gakv1';
+const NONCE_BYTES = 12;
+const KEY_BYTES = 32;
+class AesGatewayKeyLocatorCodec {
+    constructor(secretOrOptions) {
+        this.ring = new Map();
+        const options = typeof secretOrOptions === 'string'
+            ? { active: { kid: 'default', secret: secretOrOptions } }
+            : secretOrOptions;
+        this.active = normalizeSecret(options.active);
+        this.ring.set(this.active.kid, this.active.key);
+        for (const previous of options.previous ?? []) {
+            const normalized = normalizeSecret(previous);
+            if (this.ring.has(normalized.kid)) {
+                throw new Error(`Duplicate Gateway key locator key id: ${normalized.kid}`);
+            }
+            this.ring.set(normalized.kid, normalized.key);
+        }
+    }
+    encode(payload) {
+        const nonce = (0, node_crypto_1.randomBytes)(NONCE_BYTES);
+        const aad = Buffer.from(`${PREFIX}.${this.active.kid}`);
+        const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', this.active.key, nonce);
+        cipher.setAAD(aad);
+        const plaintext = Buffer.from(JSON.stringify(payload), 'utf8');
+        const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return [
+            PREFIX,
+            this.active.kid,
+            nonce.toString('base64url'),
+            ciphertext.toString('base64url'),
+            tag.toString('base64url'),
+        ].join('.');
+    }
+    decode(locator) {
+        const parts = locator.split('.');
+        if (parts.length !== 5 || parts[0] !== PREFIX) {
+            return undefined;
+        }
+        const kid = parts[1];
+        const key = this.ring.get(kid);
+        if (!key) {
+            return undefined;
+        }
+        try {
+            const nonce = Buffer.from(parts[2], 'base64url');
+            const ciphertext = Buffer.from(parts[3], 'base64url');
+            const tag = Buffer.from(parts[4], 'base64url');
+            const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, nonce);
+            decipher.setAAD(Buffer.from(`${PREFIX}.${kid}`));
+            decipher.setAuthTag(tag);
+            const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+            const parsed = JSON.parse(plaintext.toString('utf8'));
+            if (typeof parsed.owner !== 'string'
+                || typeof parsed.keyId !== 'string'
+                || (parsed.deployment !== 'local' && parsed.deployment !== 'cloud')) {
+                return undefined;
+            }
+            return {
+                owner: parsed.owner,
+                keyId: parsed.keyId,
+                deployment: parsed.deployment,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+exports.AesGatewayKeyLocatorCodec = AesGatewayKeyLocatorCodec;
+function normalizeSecret(input) {
+    const kid = input.kid.trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(kid)) {
+        throw new Error('Gateway key locator key id is invalid');
+    }
+    if (!input.secret.trim()) {
+        throw new Error('Gateway key locator secret is required');
+    }
+    return {
+        kid,
+        key: (0, node_crypto_1.createHash)('sha256').update(input.secret).digest().subarray(0, KEY_BYTES),
+    };
+}
+function createGatewayKeyLocator(owner, deployment, codec) {
+    return codec.encode({
+        owner,
+        deployment,
+        keyId: `gak_${(0, node_crypto_1.randomBytes)(18).toString('base64url')}`,
+    });
+}
+//# sourceMappingURL=GatewayKeyLocatorCodec.js.map

package/dist/api/ai-gateway/auth/GatewayKeyLocatorCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GatewayKeyLocatorCodec.js","sourceRoot":"","sources":["../../../../src/api/ai-gateway/auth/GatewayKeyLocatorCodec.ts"],"names":[],"mappings":"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","sourcesContent":["import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';\nimport type { GatewayDeployment } from './GatewayApiKey';\n\nexport interface GatewayKeyLocatorPayload {\n  owner: string;\n  keyId: string;\n  deployment: GatewayDeployment;\n}\n\nexport interface GatewayKeyLocatorCodec {\n  encode(payload: GatewayKeyLocatorPayload): string;\n  decode(locator: string): GatewayKeyLocatorPayload | undefined;\n}\n\nexport interface GatewayKeyLocatorSecret {\n  kid: string;\n  secret: string;\n}\n\nexport interface AesGatewayKeyLocatorCodecOptions {\n  active: GatewayKeyLocatorSecret;\n  previous?: GatewayKeyLocatorSecret[];\n}\n\nconst PREFIX = 'gakv1';\nconst NONCE_BYTES = 12;\nconst KEY_BYTES = 32;\n\nexport class AesGatewayKeyLocatorCodec implements GatewayKeyLocatorCodec {\n  private readonly active: { kid: string; key: Buffer };\n  private readonly ring = new Map<string, Buffer>();\n\n  public constructor(secretOrOptions: string | AesGatewayKeyLocatorCodecOptions) {\n    const options = typeof secretOrOptions === 'string'\n      ? { active: { kid: 'default', secret: secretOrOptions } }\n      : secretOrOptions;\n    this.active = normalizeSecret(options.active);\n    this.ring.set(this.active.kid, this.active.key);\n    for (const previous of options.previous ?? []) {\n      const normalized = normalizeSecret(previous);\n      if (this.ring.has(normalized.kid)) {\n        throw new Error(`Duplicate Gateway key locator key id: ${normalized.kid}`);\n      }\n      this.ring.set(normalized.kid, normalized.key);\n    }\n  }\n\n  public encode(payload: GatewayKeyLocatorPayload): string {\n    const nonce = randomBytes(NONCE_BYTES);\n    const aad = Buffer.from(`${PREFIX}.${this.active.kid}`);\n    const cipher = createCipheriv('aes-256-gcm', this.active.key, nonce);\n    cipher.setAAD(aad);\n    const plaintext = Buffer.from(JSON.stringify(payload), 'utf8');\n    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);\n    const tag = cipher.getAuthTag();\n    return [\n      PREFIX,\n      this.active.kid,\n      nonce.toString('base64url'),\n      ciphertext.toString('base64url'),\n      tag.toString('base64url'),\n    ].join('.');\n  }\n\n  public decode(locator: string): GatewayKeyLocatorPayload | undefined {\n    const parts = locator.split('.');\n    if (parts.length !== 5 || parts[0] !== PREFIX) {\n      return undefined;\n    }\n    const kid = parts[1];\n    const key = this.ring.get(kid);\n    if (!key) {\n      return undefined;\n    }\n    try {\n      const nonce = Buffer.from(parts[2], 'base64url');\n      const ciphertext = Buffer.from(parts[3], 'base64url');\n      const tag = Buffer.from(parts[4], 'base64url');\n      const decipher = createDecipheriv('aes-256-gcm', key, nonce);\n      decipher.setAAD(Buffer.from(`${PREFIX}.${kid}`));\n      decipher.setAuthTag(tag);\n      const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);\n      const parsed = JSON.parse(plaintext.toString('utf8')) as Record<string, unknown>;\n      if (\n        typeof parsed.owner !== 'string'\n        || typeof parsed.keyId !== 'string'\n        || (parsed.deployment !== 'local' && parsed.deployment !== 'cloud')\n      ) {\n        return undefined;\n      }\n      return {\n        owner: parsed.owner,\n        keyId: parsed.keyId,\n        deployment: parsed.deployment,\n      };\n    } catch {\n      return undefined;\n    }\n  }\n}\n\nfunction normalizeSecret(input: GatewayKeyLocatorSecret): { kid: string; key: Buffer } {\n  const kid = input.kid.trim();\n  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(kid)) {\n    throw new Error('Gateway key locator key id is invalid');\n  }\n  if (!input.secret.trim()) {\n    throw new Error('Gateway key locator secret is required');\n  }\n  return {\n    kid,\n    key: createHash('sha256').update(input.secret).digest().subarray(0, KEY_BYTES),\n  };\n}\n\nexport function createGatewayKeyLocator(\n  owner: string,\n  deployment: GatewayDeployment,\n  codec: GatewayKeyLocatorCodec,\n): string {\n  return codec.encode({\n    owner,\n    deployment,\n    keyId: `gak_${randomBytes(18).toString('base64url')}`,\n  });\n}\n"]}

package/dist/api/ai-gateway/auth/GatewayPrincipal.d.ts

@@ -0,0 +1,20 @@
+import type { AuthContext, SolidAuthContext } from '../../auth/AuthContext';
+export interface GatewayKeyPrincipal {
+    webId: string;
+    accountId?: string;
+    scopes: string[];
+    keyId: string;
+}
+export declare function isGatewayApiKeyPrincipal(auth: AuthContext | undefined): auth is SolidAuthContext & {
+    viaGatewayApiKey: true;
+    gatewayKeyId: string;
+    scopes: string[];
+};
+export declare function isInternalGatewayInvocationPrincipal(auth: AuthContext | undefined): auth is SolidAuthContext & {
+    viaGatewayApiKey: true;
+    internalInvocation: true;
+    gatewayKeyId: string;
+    scopes: string[];
+};
+export declare function canManageGatewayKeys(auth: AuthContext | undefined): boolean;
+export declare function ownerWebIdForGatewayKeyManagement(auth: AuthContext, requestedOwner: unknown): string | undefined;

package/dist/api/ai-gateway/auth/GatewayPrincipal.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGatewayApiKeyPrincipal = isGatewayApiKeyPrincipal;
+exports.isInternalGatewayInvocationPrincipal = isInternalGatewayInvocationPrincipal;
+exports.canManageGatewayKeys = canManageGatewayKeys;
+exports.ownerWebIdForGatewayKeyManagement = ownerWebIdForGatewayKeyManagement;
+function isGatewayApiKeyPrincipal(auth) {
+    return auth?.type === 'solid' && auth.viaGatewayApiKey === true;
+}
+function isInternalGatewayInvocationPrincipal(auth) {
+    return isGatewayApiKeyPrincipal(auth) && auth.internalInvocation === true;
+}
+function canManageGatewayKeys(auth) {
+    if (!auth) {
+        return false;
+    }
+    if (isGatewayApiKeyPrincipal(auth)) {
+        return false;
+    }
+    if (auth.type === 'solid') {
+        return Boolean(auth.webId);
+    }
+    return hasGatewayKeyManagementScope(auth);
+}
+function ownerWebIdForGatewayKeyManagement(auth, requestedOwner) {
+    if (auth.type === 'solid') {
+        return auth.webId;
+    }
+    if (hasGatewayKeyManagementScope(auth) && typeof requestedOwner === 'string' && requestedOwner.trim()) {
+        return requestedOwner.trim();
+    }
+    return undefined;
+}
+function hasGatewayKeyManagementScope(auth) {
+    return auth.type === 'service' && auth.scopes.includes('gateway:keys:write');
+}
+//# sourceMappingURL=GatewayPrincipal.js.map

package/dist/api/ai-gateway/auth/GatewayPrincipal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GatewayPrincipal.js","sourceRoot":"","sources":["../../../../src/api/ai-gateway/auth/GatewayPrincipal.ts"],"names":[],"mappings":";;AASA,4DAMC;AAED,oFAOC;AAED,oDAWC;AAED,8EAWC;AAzCD,SAAgB,wBAAwB,CAAC,IAA6B;IAKpE,OAAO,IAAI,EAAE,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,gBAAgB,KAAK,IAAI,CAAC;AAClE,CAAC;AAED,SAAgB,oCAAoC,CAAC,IAA6B;IAMhF,OAAO,wBAAwB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,kBAAkB,KAAK,IAAI,CAAC;AAC5E,CAAC;AAED,SAAgB,oBAAoB,CAAC,IAA6B;IAChE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,4BAA4B,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,SAAgB,iCAAiC,CAC/C,IAAiB,EACjB,cAAuB;IAEvB,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IACD,IAAI,4BAA4B,CAAC,IAAI,CAAC,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC;QACtG,OAAO,cAAc,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,4BAA4B,CAAC,IAAiB;IACrD,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAC/E,CAAC","sourcesContent":["import type { AuthContext, ServiceAuthContext, SolidAuthContext } from '../../auth/AuthContext';\n\nexport interface GatewayKeyPrincipal {\n  webId: string;\n  accountId?: string;\n  scopes: string[];\n  keyId: string;\n}\n\nexport function isGatewayApiKeyPrincipal(auth: AuthContext | undefined): auth is SolidAuthContext & {\n  viaGatewayApiKey: true;\n  gatewayKeyId: string;\n  scopes: string[];\n} {\n  return auth?.type === 'solid' && auth.viaGatewayApiKey === true;\n}\n\nexport function isInternalGatewayInvocationPrincipal(auth: AuthContext | undefined): auth is SolidAuthContext & {\n  viaGatewayApiKey: true;\n  internalInvocation: true;\n  gatewayKeyId: string;\n  scopes: string[];\n} {\n  return isGatewayApiKeyPrincipal(auth) && auth.internalInvocation === true;\n}\n\nexport function canManageGatewayKeys(auth: AuthContext | undefined): boolean {\n  if (!auth) {\n    return false;\n  }\n  if (isGatewayApiKeyPrincipal(auth)) {\n    return false;\n  }\n  if (auth.type === 'solid') {\n    return Boolean(auth.webId);\n  }\n  return hasGatewayKeyManagementScope(auth);\n}\n\nexport function ownerWebIdForGatewayKeyManagement(\n  auth: AuthContext,\n  requestedOwner: unknown,\n): string | undefined {\n  if (auth.type === 'solid') {\n    return auth.webId;\n  }\n  if (hasGatewayKeyManagementScope(auth) && typeof requestedOwner === 'string' && requestedOwner.trim()) {\n    return requestedOwner.trim();\n  }\n  return undefined;\n}\n\nfunction hasGatewayKeyManagementScope(auth: AuthContext): auth is ServiceAuthContext {\n  return auth.type === 'service' && auth.scopes.includes('gateway:keys:write');\n}\n"]}

package/dist/api/ai-gateway/auth/InvocationTokenCodec.d.ts

@@ -0,0 +1,41 @@
+import type { GatewayDeployment } from './GatewayApiKey';
+import type { GatewayKeyLocatorSecret } from './GatewayKeyLocatorCodec';
+export interface InvocationTokenClaims {
+    version: 1;
+    kid: string;
+    deployment: GatewayDeployment;
+    audience: string;
+    issuer: string;
+    webId: string;
+    scopes: string[];
+    issuedAt: Date;
+    expiresAt: Date;
+    jti: string;
+}
+export interface InvocationTokenInput {
+    deployment: GatewayDeployment;
+    audience: string;
+    issuer: string;
+    webId: string;
+    scopes: string[];
+    issuedAt: Date;
+    expiresAt: Date;
+    jti?: string;
+}
+export interface InvocationTokenCodec {
+    encode(input: InvocationTokenInput): string;
+    decode(token: string): InvocationTokenClaims | undefined;
+}
+export interface AesInvocationTokenCodecOptions {
+    active: GatewayKeyLocatorSecret;
+    previous?: GatewayKeyLocatorSecret[];
+}
+export declare class AesInvocationTokenCodec implements InvocationTokenCodec {
+    private readonly active;
+    private readonly ring;
+    constructor(options: AesInvocationTokenCodecOptions);
+    encode(input: InvocationTokenInput): string;
+    decode(token: string): InvocationTokenClaims | undefined;
+}
+export declare function requireCanonicalOrigin(value: string, name?: string): string;
+export declare function requireCanonicalWebId(value: string): string;

package/dist/api/ai-gateway/auth/InvocationTokenCodec.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AesInvocationTokenCodec = void 0;
+exports.requireCanonicalOrigin = requireCanonicalOrigin;
+exports.requireCanonicalWebId = requireCanonicalWebId;
+const node_crypto_1 = require("node:crypto");
+const PREFIX = 'xpod_inv_v1';
+const AAD_CONTEXT = 'xpod:gateway:internal-invocation:v1';
+const NONCE_BYTES = 12;
+const KEY_BYTES = 32;
+const MAX_TOKEN_LENGTH = 8_192;
+const MAX_CIPHERTEXT_BYTES = 4_096;
+const MAX_TTL_MS = 15 * 60_000;
+const MAX_SCOPES = 8;
+class AesInvocationTokenCodec {
+    constructor(options) {
+        this.ring = new Map();
+        this.active = normalizeSecret(options.active);
+        this.ring.set(this.active.kid, this.active.key);
+        for (const previous of options.previous ?? []) {
+            const normalized = normalizeSecret(previous);
+            if (this.ring.has(normalized.kid)) {
+                throw new Error(`Duplicate invocation token key id: ${normalized.kid}`);
+            }
+            this.ring.set(normalized.kid, normalized.key);
+        }
+    }
+    encode(input) {
+        const webId = requireCanonicalWebId(input.webId);
+        const audience = requireCanonicalOrigin(input.audience, 'audience');
+        const issuer = requireCanonicalOrigin(input.issuer, 'issuer');
+        const scopes = requireScopes(input.scopes);
+        const issuedAt = requireTimestamp(input.issuedAt, 'issuedAt');
+        const expiresAt = requireTimestamp(input.expiresAt, 'expiresAt');
+        if (expiresAt <= issuedAt || expiresAt - issuedAt > MAX_TTL_MS) {
+            throw new Error(`Invocation token TTL must be between 1 and ${MAX_TTL_MS} milliseconds`);
+        }
+        const payload = {
+            v: 1,
+            kid: this.active.kid,
+            deployment: input.deployment,
+            aud: audience,
+            iss: issuer,
+            webId,
+            scopes,
+            iat: issuedAt,
+            exp: expiresAt,
+            jti: input.jti ?? (0, node_crypto_1.randomBytes)(18).toString('base64url'),
+        };
+        const nonce = (0, node_crypto_1.randomBytes)(NONCE_BYTES);
+        const aad = Buffer.from(`${AAD_CONTEXT}.${this.active.kid}`);
+        const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', this.active.key, nonce);
+        cipher.setAAD(aad);
+        const ciphertext = Buffer.concat([
+            cipher.update(JSON.stringify(payload), 'utf8'),
+            cipher.final(),
+        ]);
+        const tag = cipher.getAuthTag();
+        return [
+            PREFIX,
+            this.active.kid,
+            nonce.toString('base64url'),
+            ciphertext.toString('base64url'),
+            tag.toString('base64url'),
+        ].join('.');
+    }
+    decode(token) {
+        if (token.length > MAX_TOKEN_LENGTH) {
+            return undefined;
+        }
+        const parts = token.split('.');
+        if (parts.length !== 5 || parts[0] !== PREFIX) {
+            return undefined;
+        }
+        const kid = parts[1];
+        const key = this.ring.get(kid);
+        if (!key
+            || !parts.slice(1).every((part) => /^[A-Za-z0-9_-]+$/u.test(part))) {
+            return undefined;
+        }
+        try {
+            const nonce = decodeCanonicalBase64Url(parts[2]);
+            const ciphertext = decodeCanonicalBase64Url(parts[3]);
+            const tag = decodeCanonicalBase64Url(parts[4]);
+            if (!nonce || !ciphertext || !tag) {
+                return undefined;
+            }
+            if (nonce.length !== NONCE_BYTES
+                || ciphertext.length === 0
+                || ciphertext.length > MAX_CIPHERTEXT_BYTES
+                || tag.length !== 16) {
+                return undefined;
+            }
+            const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, nonce);
+            decipher.setAAD(Buffer.from(`${AAD_CONTEXT}.${kid}`));
+            decipher.setAuthTag(tag);
+            const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+            const parsed = JSON.parse(plaintext.toString('utf8'));
+            const keys = Object.keys(parsed).sort();
+            if (keys.join(',') !== 'aud,deployment,exp,iat,iss,jti,kid,scopes,v,webId'
+                ||
+                    parsed.v !== 1
+                || parsed.kid !== kid
+                || (parsed.deployment !== 'local' && parsed.deployment !== 'cloud')
+                || typeof parsed.aud !== 'string'
+                || typeof parsed.iss !== 'string'
+                || typeof parsed.webId !== 'string'
+                || !Array.isArray(parsed.scopes)
+                || typeof parsed.iat !== 'number'
+                || typeof parsed.exp !== 'number'
+                || typeof parsed.jti !== 'string'
+                || !/^[A-Za-z0-9_-]{16,128}$/u.test(parsed.jti)) {
+                return undefined;
+            }
+            const audience = requireCanonicalOrigin(parsed.aud, 'audience');
+            const issuer = requireCanonicalOrigin(parsed.iss, 'issuer');
+            const webId = requireCanonicalWebId(parsed.webId);
+            const scopes = requireScopes(parsed.scopes);
+            const issuedAt = requireEpoch(parsed.iat);
+            const expiresAt = requireEpoch(parsed.exp);
+            if (expiresAt <= issuedAt || expiresAt - issuedAt > MAX_TTL_MS) {
+                return undefined;
+            }
+            return {
+                version: 1,
+                kid,
+                deployment: parsed.deployment,
+                audience,
+                issuer,
+                webId,
+                scopes,
+                issuedAt: new Date(issuedAt),
+                expiresAt: new Date(expiresAt),
+                jti: parsed.jti,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+exports.AesInvocationTokenCodec = AesInvocationTokenCodec;
+function requireCanonicalOrigin(value, name = 'origin') {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Invocation token ${name} must be a canonical HTTP(S) origin`);
+    }
+    if ((url.protocol !== 'https:' && url.protocol !== 'http:')
+        || url.username
+        || url.password
+        || url.pathname !== '/'
+        || url.search
+        || url.hash
+        || url.origin !== value) {
+        throw new Error(`Invocation token ${name} must be a canonical HTTP(S) origin`);
+    }
+    return url.origin;
+}
+function decodeCanonicalBase64Url(value) {
+    const decoded = Buffer.from(value, 'base64url');
+    return decoded.toString('base64url') === value ? decoded : undefined;
+}
+function normalizeSecret(input) {
+    const kid = input.kid.trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u.test(kid)) {
+        throw new Error('Invocation token key id is invalid');
+    }
+    if (!input.secret.trim()) {
+        throw new Error('Invocation token secret is required');
+    }
+    return {
+        kid,
+        key: (0, node_crypto_1.createHash)('sha256')
+            .update(`${AAD_CONTEXT}\0`, 'utf8')
+            .update(input.secret, 'utf8')
+            .digest()
+            .subarray(0, KEY_BYTES),
+    };
+}
+function requireCanonicalWebId(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('Invocation token WebID must be a canonical HTTP(S) URL');
+    }
+    if ((url.protocol !== 'https:' && url.protocol !== 'http:')
+        || url.username
+        || url.password
+        || url.href !== value) {
+        throw new Error('Invocation token WebID must be a canonical HTTP(S) URL');
+    }
+    return url.href;
+}
+function requireScopes(value) {
+    if (value.length === 0
+        || value.length > MAX_SCOPES
+        || value.some((scope) => typeof scope !== 'string' || !/^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$/u.test(scope))
+        || new Set(value).size !== value.length) {
+        throw new Error('Invocation token scopes are invalid');
+    }
+    return [...value];
+}
+function requireTimestamp(value, name) {
+    const timestamp = value.getTime();
+    if (!Number.isSafeInteger(timestamp) || timestamp < 0) {
+        throw new Error(`Invocation token ${name} is invalid`);
+    }
+    return timestamp;
+}
+function requireEpoch(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error('Invocation token timestamp is invalid');
+    }
+    return value;
+}
+//# sourceMappingURL=InvocationTokenCodec.js.map