@undefineds.co/xpod 0.4.15 → 0.4.17

package/dist/api/tasks/TaskCredentialSchema.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskCredentialSchema = exports.taskCredentialsPg = exports.taskCredentialsSqlite = void 0;
+exports.ensureTaskCredentialTables = ensureTaskCredentialTables;
+const drizzle_orm_1 = require("drizzle-orm");
+const pg_core_1 = require("drizzle-orm/pg-core");
+const integer_1 = require("drizzle-orm/pg-core/columns/integer");
+const sqlite_core_1 = require("drizzle-orm/sqlite-core");
+/**
+ * Task-layer credential records: the runtime's own copy of a user's CSS client credentials.
+ *
+ * This table belongs to the task layer, not to the API: the API only ever uses a credential the
+ * caller brought with that request, while background execution needs one on file when nobody is
+ * present. Keeping it in its own database (local mode: its own SQLite file) is what makes that
+ * boundary real instead of a naming convention.
+ *
+ * `sealed_secret` is encrypted with the deployment key (decision 6), and the row records which
+ * key sealed it so rotation keeps old rows decryptable.
+ */
+exports.taskCredentialsSqlite = (0, sqlite_core_1.sqliteTable)('task_credential', {
+    credentialId: (0, sqlite_core_1.text)('credential_id').primaryKey(),
+    ownerWebId: (0, sqlite_core_1.text)('owner_web_id').notNull(),
+    issuer: (0, sqlite_core_1.text)('issuer').notNull(),
+    clientId: (0, sqlite_core_1.text)('client_id').notNull(),
+    sealedSecret: (0, sqlite_core_1.text)('sealed_secret').notNull(),
+    sealedSecretKeyId: (0, sqlite_core_1.text)('sealed_secret_key_id').notNull(),
+    credentialVersion: (0, sqlite_core_1.integer)('credential_version').notNull().default(1),
+    status: (0, sqlite_core_1.text)('status').notNull(),
+    createdAt: (0, sqlite_core_1.integer)('created_at').notNull(),
+    rotatedAt: (0, sqlite_core_1.integer)('rotated_at'),
+    lastUsedAt: (0, sqlite_core_1.integer)('last_used_at'),
+    expiresAt: (0, sqlite_core_1.integer)('expires_at'),
+});
+exports.taskCredentialsPg = (0, pg_core_1.pgTable)('task_credential', {
+    credentialId: (0, pg_core_1.text)('credential_id').primaryKey(),
+    ownerWebId: (0, pg_core_1.text)('owner_web_id').notNull(),
+    issuer: (0, pg_core_1.text)('issuer').notNull(),
+    clientId: (0, pg_core_1.text)('client_id').notNull(),
+    sealedSecret: (0, pg_core_1.text)('sealed_secret').notNull(),
+    sealedSecretKeyId: (0, pg_core_1.text)('sealed_secret_key_id').notNull(),
+    credentialVersion: (0, integer_1.integer)('credential_version').notNull().default(1),
+    status: (0, pg_core_1.text)('status').notNull(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull(),
+    rotatedAt: (0, pg_core_1.timestamp)('rotated_at', { withTimezone: true }),
+    lastUsedAt: (0, pg_core_1.timestamp)('last_used_at', { withTimezone: true }),
+    expiresAt: (0, pg_core_1.timestamp)('expires_at', { withTimezone: true }),
+});
+exports.taskCredentialSchema = {
+    sqlite: { taskCredentials: exports.taskCredentialsSqlite },
+    pg: { taskCredentials: exports.taskCredentialsPg },
+};
+/** Creates the task-layer table on a fresh database; existing rows are left untouched. */
+async function ensureTaskCredentialTables(db) {
+    if (typeof db.run === 'function') {
+        db.run((0, drizzle_orm_1.sql) `
+      CREATE TABLE IF NOT EXISTS task_credential (
+        credential_id TEXT PRIMARY KEY,
+        owner_web_id TEXT NOT NULL,
+        issuer TEXT NOT NULL,
+        client_id TEXT NOT NULL,
+        sealed_secret TEXT NOT NULL,
+        sealed_secret_key_id TEXT NOT NULL,
+        credential_version INTEGER NOT NULL DEFAULT 1,
+        status TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        rotated_at INTEGER,
+        last_used_at INTEGER,
+        expires_at INTEGER
+      )
+    `);
+        db.run((0, drizzle_orm_1.sql) `CREATE INDEX IF NOT EXISTS task_credential_owner ON task_credential (owner_web_id)`);
+        return;
+    }
+    await db.execute((0, drizzle_orm_1.sql) `
+    CREATE TABLE IF NOT EXISTS task_credential (
+      credential_id TEXT PRIMARY KEY,
+      owner_web_id TEXT NOT NULL,
+      issuer TEXT NOT NULL,
+      client_id TEXT NOT NULL,
+      sealed_secret TEXT NOT NULL,
+      sealed_secret_key_id TEXT NOT NULL,
+      credential_version INTEGER NOT NULL DEFAULT 1,
+      status TEXT NOT NULL,
+      created_at TIMESTAMPTZ NOT NULL,
+      rotated_at TIMESTAMPTZ,
+      last_used_at TIMESTAMPTZ,
+      expires_at TIMESTAMPTZ
+    )
+  `);
+    await db.execute((0, drizzle_orm_1.sql) `CREATE INDEX IF NOT EXISTS task_credential_owner ON task_credential (owner_web_id)`);
+}
+//# sourceMappingURL=TaskCredentialSchema.js.map

package/dist/api/tasks/TaskCredentialStore.d.ts

@@ -0,0 +1,129 @@
+import type { SecretCellVault } from '../../security/secret-cell';
+import type { TaskCredentialSource } from '../ai-gateway/pod/OwnerPodAccess';
+import type { TaskCredentialDatabase } from './TaskCredentialDatabase';
+/** Stable reference a task binding carries instead of a secret. */
+export type TaskCredentialRef = string;
+/**
+ * Every generated reference starts with this, which is what lets a binding tell "this id names a
+ * task-layer grant" from "this id is a Pod-stored credential".
+ */
+export declare const TASK_CREDENTIAL_REF_PREFIX = "taskcred_";
+/**
+ * `pending` is a grant that exists but must not be used yet: the user asked for it, and the
+ * runtime activates it only once the grant is confirmed. `expired` and `revoked` are terminal for
+ * execution but keep the row, so audits and rotation keep their history.
+ */
+export type TaskCredentialStatus = 'pending' | 'active' | 'revoked' | 'expired';
+/** Everything an executor needs to open the owner's Pod; never logged or persisted elsewhere. */
+export interface TaskCredentialLease {
+    credentialRef: TaskCredentialRef;
+    ownerWebId: string;
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    version: number;
+}
+/** Metadata about a grant, safe to return to a UI. */
+export interface TaskCredentialSummary {
+    credentialRef: TaskCredentialRef;
+    ownerWebId: string;
+    issuer: string;
+    clientId: string;
+    version: number;
+    status: TaskCredentialStatus;
+    createdAt: Date;
+    rotatedAt?: Date;
+    lastUsedAt?: Date;
+    expiresAt?: Date;
+}
+export declare const TASK_CREDENTIAL_NOT_FOUND = "task_credential_not_found";
+export declare const TASK_CREDENTIAL_NOT_ACTIVE = "task_credential_not_active";
+export declare const TASK_CREDENTIAL_VERSION_CONFLICT = "task_credential_version_conflict";
+export declare const TASK_CREDENTIAL_OWNER_MISMATCH = "task_credential_owner_mismatch";
+export declare const TASK_CREDENTIAL_ENCRYPTION_FAILED = "task_credential_encryption_failed";
+export interface TaskCredentialStoreOptions {
+    database: TaskCredentialDatabase;
+    /** Deployment-key vault. The secret is stored encrypted, never in the clear. */
+    vault: SecretCellVault;
+    now?: () => Date;
+    /** Stable id for a new grant; injectable so callers can make granting idempotent. */
+    newCredentialRef?: (input: {
+        ownerWebId: string;
+        issuer: string;
+    }) => string;
+}
+export interface GrantTaskCredentialInput {
+    ownerWebId: string;
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    /** `pending` until the grant is confirmed; defaults to `pending`. */
+    status?: Extract<TaskCredentialStatus, 'pending' | 'active'>;
+    expiresAt?: Date;
+    /** Reuse this reference to make a retried grant idempotent. */
+    credentialRef?: TaskCredentialRef;
+}
+/**
+ * The task layer's own credential store.
+ *
+ * Reading a lease requires an explicit owner and an `active` row at the expected version, so a
+ * stale task, a revoked grant or another user's reference cannot open somebody else's Pod.
+ */
+export declare class TaskCredentialStore {
+    private readonly logger;
+    private readonly db;
+    private readonly table;
+    private readonly vault;
+    private readonly now;
+    private readonly newCredentialRef;
+    private readonly ready;
+    private initError?;
+    constructor(options: TaskCredentialStoreOptions);
+    /** Grant, or idempotently re-grant, a credential for one user and issuer. */
+    grant(input: GrantTaskCredentialInput): Promise<TaskCredentialSummary>;
+    /** Confirm a grant so executions may use it. */
+    activate(credentialRef: TaskCredentialRef): Promise<TaskCredentialSummary>;
+    /** Replace the secret, bumping the version so older bindings stop matching. */
+    rotate(credentialRef: TaskCredentialRef, input: {
+        clientId: string;
+        clientSecret: string;
+        expectedVersion: number;
+    }): Promise<TaskCredentialSummary>;
+    /** Stop using a grant without losing its history. */
+    revoke(credentialRef: TaskCredentialRef): Promise<void>;
+    /**
+     * Open the credential for one execution.
+     *
+     * Everything that makes a grant usable is checked here: the owner the caller claims, the status,
+     * the version the binding froze, and the expiry. A refusal keeps its own reason code so the
+     * caller can tell a revoked grant from a stale one.
+     */
+    lease(input: {
+        credentialRef: TaskCredentialRef;
+        ownerWebId: string;
+        version?: number;
+        /** Check the version without extending `last_used_at`. */
+        recordUsage?: boolean;
+    }): Promise<TaskCredentialLease>;
+    /** Metadata for one user's grants; never a secret. */
+    listForOwner(ownerWebId: string): Promise<TaskCredentialSummary[]>;
+    /** The rows whose secret was sealed with a key that is no longer active. */
+    listNeedingRewrap(activeKeyId: string): Promise<TaskCredentialRef[]>;
+    private seal;
+    private openRow;
+    private findRow;
+    private requireRow;
+    private toSummary;
+    private ensureReady;
+}
+/**
+ * The task layer's credentials as Pod access needs them.
+ *
+ * `activeFor` answers "may background work use this owner's grant at all", which is what a
+ * scheduled entry needs; `forRef` answers a task binding that names its credential and version.
+ */
+export declare function createTaskCredentialSource(input: {
+    store: TaskCredentialStore;
+    /** Issuer whose grants this deployment can use; grants for other issuers are ignored. */
+    issuer: string;
+}): TaskCredentialSource;

package/dist/api/tasks/TaskCredentialStore.js

@@ -0,0 +1,341 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskCredentialStore = exports.TASK_CREDENTIAL_ENCRYPTION_FAILED = exports.TASK_CREDENTIAL_OWNER_MISMATCH = exports.TASK_CREDENTIAL_VERSION_CONFLICT = exports.TASK_CREDENTIAL_NOT_ACTIVE = exports.TASK_CREDENTIAL_NOT_FOUND = exports.TASK_CREDENTIAL_REF_PREFIX = void 0;
+exports.createTaskCredentialSource = createTaskCredentialSource;
+const node_crypto_1 = require("node:crypto");
+const drizzle_orm_1 = require("drizzle-orm");
+const global_logger_factory_1 = require("global-logger-factory");
+const db_1 = require("../../identity/drizzle/db");
+const TaskCredentialSchema_1 = require("./TaskCredentialSchema");
+/**
+ * Every generated reference starts with this, which is what lets a binding tell "this id names a
+ * task-layer grant" from "this id is a Pod-stored credential".
+ */
+exports.TASK_CREDENTIAL_REF_PREFIX = 'taskcred_';
+exports.TASK_CREDENTIAL_NOT_FOUND = 'task_credential_not_found';
+exports.TASK_CREDENTIAL_NOT_ACTIVE = 'task_credential_not_active';
+exports.TASK_CREDENTIAL_VERSION_CONFLICT = 'task_credential_version_conflict';
+exports.TASK_CREDENTIAL_OWNER_MISMATCH = 'task_credential_owner_mismatch';
+exports.TASK_CREDENTIAL_ENCRYPTION_FAILED = 'task_credential_encryption_failed';
+/**
+ * The task layer's own credential store.
+ *
+ * Reading a lease requires an explicit owner and an `active` row at the expected version, so a
+ * stale task, a revoked grant or another user's reference cannot open somebody else's Pod.
+ */
+class TaskCredentialStore {
+    constructor(options) {
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.db = options.database.db;
+        this.table = options.database.schema.taskCredentials;
+        this.vault = options.vault;
+        this.now = options.now ?? (() => new Date());
+        // One grant per owner and issuer: the reference is derived, so a retried registration lands on
+        // the same row instead of leaving a second credential behind.
+        this.newCredentialRef = options.newCredentialRef
+            ?? ((input) => `${exports.TASK_CREDENTIAL_REF_PREFIX}${(0, node_crypto_1.createHash)('sha256').update(`${input.issuer}\u0000${input.ownerWebId}`).digest('hex').slice(0, 32)}`);
+        this.ready = (0, TaskCredentialSchema_1.ensureTaskCredentialTables)(this.db).catch((error) => {
+            this.initError = error;
+        });
+    }
+    /** Grant, or idempotently re-grant, a credential for one user and issuer. */
+    async grant(input) {
+        await this.ensureReady();
+        const credentialRef = input.credentialRef ?? this.newCredentialRef(input);
+        const existing = await this.findRow(credentialRef);
+        if (existing) {
+            if (String(existing.ownerWebId) !== input.ownerWebId || String(existing.issuer) !== input.issuer) {
+                throw new Error(exports.TASK_CREDENTIAL_OWNER_MISMATCH);
+            }
+            // The same reference with the same secret is a retry, not a rotation: keep the version.
+            const lease = await this.openRow(existing);
+            if (lease.clientId === input.clientId && lease.clientSecret === input.clientSecret) {
+                if (input.status === 'active' && String(existing.status) === 'pending') {
+                    return await this.activate(credentialRef);
+                }
+                return this.toSummary(existing);
+            }
+            return await this.rotate(credentialRef, {
+                clientId: input.clientId,
+                clientSecret: input.clientSecret,
+                expectedVersion: Number(existing.credentialVersion),
+            });
+        }
+        const sealed = await this.seal({ credentialRef, ownerWebId: input.ownerWebId, issuer: input.issuer, clientId: input.clientId, clientSecret: input.clientSecret });
+        const createdAt = (0, db_1.toDbTimestamp)(this.db, this.now());
+        await this.db.insert(this.table).values({
+            credentialId: credentialRef,
+            ownerWebId: input.ownerWebId,
+            issuer: input.issuer,
+            clientId: input.clientId,
+            sealedSecret: sealed.sealedSecret,
+            sealedSecretKeyId: sealed.keyId,
+            credentialVersion: 1,
+            status: input.status ?? 'pending',
+            createdAt,
+            rotatedAt: createdAt,
+            ...(input.expiresAt ? { expiresAt: (0, db_1.toDbTimestamp)(this.db, input.expiresAt) } : {}),
+        });
+        this.logger.info(`Granted a task credential for ${input.ownerWebId} (${input.status ?? 'pending'})`);
+        const created = await this.findRow(credentialRef);
+        if (!created) {
+            throw new Error(exports.TASK_CREDENTIAL_NOT_FOUND);
+        }
+        return this.toSummary(created);
+    }
+    /** Confirm a grant so executions may use it. */
+    async activate(credentialRef) {
+        await this.ensureReady();
+        const row = await this.requireRow(credentialRef);
+        if (String(row.status) === 'revoked' || String(row.status) === 'expired') {
+            throw new Error(exports.TASK_CREDENTIAL_NOT_ACTIVE);
+        }
+        if (String(row.status) !== 'active') {
+            await this.db
+                .update(this.table)
+                .set({ status: 'active' })
+                .where((0, drizzle_orm_1.eq)(this.table.credentialId, credentialRef));
+        }
+        return this.toSummary(await this.requireRow(credentialRef));
+    }
+    /** Replace the secret, bumping the version so older bindings stop matching. */
+    async rotate(credentialRef, input) {
+        await this.ensureReady();
+        const row = await this.requireRow(credentialRef);
+        if (Number(row.credentialVersion) !== input.expectedVersion) {
+            throw new Error(`${exports.TASK_CREDENTIAL_VERSION_CONFLICT}:${row.credentialVersion}`);
+        }
+        const sealed = await this.seal({
+            credentialRef,
+            ownerWebId: String(row.ownerWebId),
+            issuer: String(row.issuer),
+            clientId: input.clientId,
+            clientSecret: input.clientSecret,
+        });
+        const nextVersion = input.expectedVersion + 1;
+        await this.db
+            .update(this.table)
+            .set({
+            clientId: input.clientId,
+            sealedSecret: sealed.sealedSecret,
+            sealedSecretKeyId: sealed.keyId,
+            credentialVersion: nextVersion,
+            status: 'active',
+            rotatedAt: (0, db_1.toDbTimestamp)(this.db, this.now()),
+        })
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(this.table.credentialId, credentialRef), (0, drizzle_orm_1.eq)(this.table.credentialVersion, input.expectedVersion)));
+        const rotated = await this.requireRow(credentialRef);
+        if (Number(rotated.credentialVersion) !== nextVersion) {
+            throw new Error(`${exports.TASK_CREDENTIAL_VERSION_CONFLICT}:${rotated.credentialVersion}`);
+        }
+        this.logger.info(`Rotated task credential ${credentialRef} to version ${nextVersion}`);
+        return this.toSummary(rotated);
+    }
+    /** Stop using a grant without losing its history. */
+    async revoke(credentialRef) {
+        await this.ensureReady();
+        await this.requireRow(credentialRef);
+        await this.db
+            .update(this.table)
+            .set({ status: 'revoked' })
+            .where((0, drizzle_orm_1.eq)(this.table.credentialId, credentialRef));
+    }
+    /**
+     * Open the credential for one execution.
+     *
+     * Everything that makes a grant usable is checked here: the owner the caller claims, the status,
+     * the version the binding froze, and the expiry. A refusal keeps its own reason code so the
+     * caller can tell a revoked grant from a stale one.
+     */
+    async lease(input) {
+        await this.ensureReady();
+        const row = await this.requireRow(input.credentialRef);
+        if (String(row.ownerWebId) !== input.ownerWebId) {
+            throw new Error(exports.TASK_CREDENTIAL_OWNER_MISMATCH);
+        }
+        if (input.version !== undefined && Number(row.credentialVersion) !== input.version) {
+            throw new Error(`${exports.TASK_CREDENTIAL_VERSION_CONFLICT}:${row.credentialVersion}`);
+        }
+        const expiresAt = (0, db_1.fromDbTimestamp)(row.expiresAt);
+        if (expiresAt && expiresAt.getTime() <= this.now().getTime()) {
+            await this.db.update(this.table).set({ status: 'expired' }).where((0, drizzle_orm_1.eq)(this.table.credentialId, input.credentialRef));
+            throw new Error(`${exports.TASK_CREDENTIAL_NOT_ACTIVE}:expired`);
+        }
+        if (String(row.status) !== 'active') {
+            throw new Error(`${exports.TASK_CREDENTIAL_NOT_ACTIVE}:${String(row.status)}`);
+        }
+        if (input.recordUsage !== false) {
+            await this.db
+                .update(this.table)
+                .set({ lastUsedAt: (0, db_1.toDbTimestamp)(this.db, this.now()) })
+                .where((0, drizzle_orm_1.eq)(this.table.credentialId, input.credentialRef));
+        }
+        const opened = await this.openRow(row);
+        return {
+            credentialRef: input.credentialRef,
+            ownerWebId: String(row.ownerWebId),
+            issuer: String(row.issuer),
+            version: Number(row.credentialVersion),
+            clientId: opened.clientId,
+            clientSecret: opened.clientSecret,
+        };
+    }
+    /** Metadata for one user's grants; never a secret. */
+    async listForOwner(ownerWebId) {
+        await this.ensureReady();
+        const rows = await this.db
+            .select()
+            .from(this.table)
+            .where((0, drizzle_orm_1.eq)(this.table.ownerWebId, ownerWebId));
+        return rows.map((row) => this.toSummary(row));
+    }
+    /** The rows whose secret was sealed with a key that is no longer active. */
+    async listNeedingRewrap(activeKeyId) {
+        await this.ensureReady();
+        const rows = await this.db.select().from(this.table);
+        return rows
+            .filter((row) => String(row.sealedSecretKeyId) !== activeKeyId)
+            .map((row) => String(row.credentialId));
+    }
+    async seal(input) {
+        let plaintext;
+        try {
+            plaintext = new TextEncoder().encode(JSON.stringify({
+                clientId: input.clientId,
+                clientSecret: input.clientSecret,
+            }));
+            const envelope = await this.vault.seal(plaintext, {
+                ownerWebId: input.ownerWebId,
+                resourceIri: `urn:xpod:task-credential:${input.credentialRef}`,
+                predicate: 'urn:xpod:taskCredential:sealedSecret',
+                field: 'clientSecret',
+                schemaVersion: 'v1',
+                provider: input.issuer,
+            });
+            return { sealedSecret: JSON.stringify(envelope), keyId: envelope.wrappedDek.keyId };
+        }
+        catch (error) {
+            this.logger.error(`Task credential encryption failed for ${input.ownerWebId}: ${String(error)}`);
+            throw new Error(exports.TASK_CREDENTIAL_ENCRYPTION_FAILED);
+        }
+        finally {
+            plaintext?.fill(0);
+        }
+    }
+    async openRow(row) {
+        let plaintext;
+        try {
+            const envelope = JSON.parse(String(row.sealedSecret));
+            plaintext = await this.vault.open(envelope, {
+                ownerWebId: String(row.ownerWebId),
+                resourceIri: `urn:xpod:task-credential:${String(row.credentialId)}`,
+                predicate: 'urn:xpod:taskCredential:sealedSecret',
+                field: 'clientSecret',
+                schemaVersion: 'v1',
+                provider: String(row.issuer),
+            });
+            const parsed = JSON.parse(new TextDecoder().decode(plaintext));
+            if (typeof parsed.clientId !== 'string' || typeof parsed.clientSecret !== 'string') {
+                throw new Error('decrypted task credential is not a client credential');
+            }
+            return { clientId: parsed.clientId, clientSecret: parsed.clientSecret };
+        }
+        catch (error) {
+            this.logger.error(`Task credential could not be opened for ${String(row.ownerWebId)}: ${String(error)}`);
+            throw new Error(exports.TASK_CREDENTIAL_ENCRYPTION_FAILED);
+        }
+        finally {
+            plaintext?.fill(0);
+        }
+    }
+    async findRow(credentialRef) {
+        const rows = await this.db
+            .select()
+            .from(this.table)
+            .where((0, drizzle_orm_1.eq)(this.table.credentialId, credentialRef))
+            .limit(1);
+        return rows[0];
+    }
+    async requireRow(credentialRef) {
+        const row = await this.findRow(credentialRef);
+        if (!row) {
+            throw new Error(exports.TASK_CREDENTIAL_NOT_FOUND);
+        }
+        return row;
+    }
+    toSummary(row) {
+        return {
+            credentialRef: String(row.credentialId),
+            ownerWebId: String(row.ownerWebId),
+            issuer: String(row.issuer),
+            clientId: String(row.clientId),
+            version: Number(row.credentialVersion),
+            status: String(row.status),
+            createdAt: (0, db_1.fromDbTimestamp)(row.createdAt) ?? this.now(),
+            ...((0, db_1.fromDbTimestamp)(row.rotatedAt) ? { rotatedAt: (0, db_1.fromDbTimestamp)(row.rotatedAt) } : {}),
+            ...((0, db_1.fromDbTimestamp)(row.lastUsedAt) ? { lastUsedAt: (0, db_1.fromDbTimestamp)(row.lastUsedAt) } : {}),
+            ...((0, db_1.fromDbTimestamp)(row.expiresAt) ? { expiresAt: (0, db_1.fromDbTimestamp)(row.expiresAt) } : {}),
+        };
+    }
+    async ensureReady() {
+        await this.ready;
+        if (this.initError) {
+            throw this.initError instanceof Error
+                ? this.initError
+                : new Error(`task_credential_table_unavailable:${String(this.initError)}`);
+        }
+    }
+}
+exports.TaskCredentialStore = TaskCredentialStore;
+/**
+ * The task layer's credentials as Pod access needs them.
+ *
+ * `activeFor` answers "may background work use this owner's grant at all", which is what a
+ * scheduled entry needs; `forRef` answers a task binding that names its credential and version.
+ */
+function createTaskCredentialSource(input) {
+    const { store, issuer } = input;
+    return {
+        async activeFor(ownerWebId) {
+            const grants = await store.listForOwner(ownerWebId);
+            const active = grants
+                .filter((grant) => grant.status === 'active' && grant.issuer === issuer)
+                .sort((left, right) => right.version - left.version)[0];
+            if (!active) {
+                return undefined;
+            }
+            const lease = await store.lease({
+                credentialRef: active.credentialRef,
+                ownerWebId,
+                version: active.version,
+            });
+            return {
+                credentialRef: lease.credentialRef,
+                version: lease.version,
+                clientId: lease.clientId,
+                clientSecret: lease.clientSecret,
+            };
+        },
+        async forRef({ credentialRef, ownerWebId, version }) {
+            try {
+                const lease = await store.lease({
+                    credentialRef,
+                    ownerWebId,
+                    ...(version !== undefined ? { version } : {}),
+                    // A version probe must not look like a use of the credential.
+                    recordUsage: false,
+                });
+                return {
+                    credentialRef: lease.credentialRef,
+                    version: lease.version,
+                    clientId: lease.clientId,
+                    clientSecret: lease.clientSecret,
+                };
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}
+//# sourceMappingURL=TaskCredentialStore.js.map

package/dist/api/tasks/index.d.ts

@@ -2,5 +2,8 @@ export { Task, TaskStatus, TaskTriggerKind, type TaskRecord, type TaskStatusType
 export { type TaskListOptions, type TaskRecordData, type TaskStore, } from './store';
 export { TaskMaterializer, type MaterializedTaskRun, type TaskMaterializerOptions, } from './TaskMaterializer';
 export { TaskService, type CreateTaskInput, type CreateTaskResult, type TaskServiceOptions, } from './TaskService';
+export { getTaskCredentialDatabase, resolveTaskCredentialDatabaseUrl, resetTaskCredentialDatabases, type TaskCredentialDatabase, } from './TaskCredentialDatabase';
+export { TASK_CREDENTIAL_ENCRYPTION_FAILED, TASK_CREDENTIAL_NOT_ACTIVE, TASK_CREDENTIAL_NOT_FOUND, TASK_CREDENTIAL_OWNER_MISMATCH, TASK_CREDENTIAL_VERSION_CONFLICT, TaskCredentialStore, type GrantTaskCredentialInput, type TaskCredentialLease, type TaskCredentialRef, type TaskCredentialStatus, type TaskCredentialStoreOptions, type TaskCredentialSummary, } from './TaskCredentialStore';
+export { ensureTaskCredentialTables, taskCredentialSchema, taskCredentialsPg, taskCredentialsSqlite, } from './TaskCredentialSchema';
 export { TASK_AUTH_CREDENTIAL_SERVICE, TaskAuthBindingKind, TaskAuthBindingService, TaskAuthBindingStatus, encodeClientCredentialsApiKey, parseClientCredentialsApiKey, type CreateTaskAuthBindingInput, type TaskAuthBindingKindType, type TaskAuthBindingRepository, type TaskAuthBindingServiceOptions, type TaskAuthBindingSnapshot, type TaskAuthBindingStatusType, type TaskAuthCredentialRecord, } from './TaskAuthBinding';
 export { InngestTaskScheduler, XPOD_TASK_MATERIALIZE_DUE_EVENT, XPOD_TASK_EVENT, XPOD_TASK_EVENT_FUNCTION_ID, XPOD_TASK_MATERIALIZE_DUE_FUNCTION_ID, type XpodTaskMaterializeDueEvent, type XpodTaskMaterializeDueEventData, type XpodTaskEvent, type XpodTaskEventData, type InngestTaskSchedulerOptions, } from './InngestTaskScheduler';

package/dist/api/tasks/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XPOD_TASK_MATERIALIZE_DUE_FUNCTION_ID = exports.XPOD_TASK_EVENT_FUNCTION_ID = exports.XPOD_TASK_EVENT = exports.XPOD_TASK_MATERIALIZE_DUE_EVENT = exports.InngestTaskScheduler = exports.parseClientCredentialsApiKey = exports.encodeClientCredentialsApiKey = exports.TaskAuthBindingStatus = exports.TaskAuthBindingService = exports.TaskAuthBindingKind = exports.TASK_AUTH_CREDENTIAL_SERVICE = exports.TaskService = exports.TaskMaterializer = exports.TaskTriggerKind = exports.TaskStatus = exports.Task = void 0;
+exports.XPOD_TASK_MATERIALIZE_DUE_FUNCTION_ID = exports.XPOD_TASK_EVENT_FUNCTION_ID = exports.XPOD_TASK_EVENT = exports.XPOD_TASK_MATERIALIZE_DUE_EVENT = exports.InngestTaskScheduler = exports.parseClientCredentialsApiKey = exports.encodeClientCredentialsApiKey = exports.TaskAuthBindingStatus = exports.TaskAuthBindingService = exports.TaskAuthBindingKind = exports.TASK_AUTH_CREDENTIAL_SERVICE = exports.taskCredentialsSqlite = exports.taskCredentialsPg = exports.taskCredentialSchema = exports.ensureTaskCredentialTables = exports.TaskCredentialStore = exports.TASK_CREDENTIAL_VERSION_CONFLICT = exports.TASK_CREDENTIAL_OWNER_MISMATCH = exports.TASK_CREDENTIAL_NOT_FOUND = exports.TASK_CREDENTIAL_NOT_ACTIVE = exports.TASK_CREDENTIAL_ENCRYPTION_FAILED = exports.resetTaskCredentialDatabases = exports.resolveTaskCredentialDatabaseUrl = exports.getTaskCredentialDatabase = exports.TaskService = exports.TaskMaterializer = exports.TaskTriggerKind = exports.TaskStatus = exports.Task = void 0;
 var schema_1 = require("./schema");
 Object.defineProperty(exports, "Task", { enumerable: true, get: function () { return schema_1.Task; } });
 Object.defineProperty(exports, "TaskStatus", { enumerable: true, get: function () { return schema_1.TaskStatus; } });
@@ -9,6 +9,22 @@ var TaskMaterializer_1 = require("./TaskMaterializer");
 Object.defineProperty(exports, "TaskMaterializer", { enumerable: true, get: function () { return TaskMaterializer_1.TaskMaterializer; } });
 var TaskService_1 = require("./TaskService");
 Object.defineProperty(exports, "TaskService", { enumerable: true, get: function () { return TaskService_1.TaskService; } });
+var TaskCredentialDatabase_1 = require("./TaskCredentialDatabase");
+Object.defineProperty(exports, "getTaskCredentialDatabase", { enumerable: true, get: function () { return TaskCredentialDatabase_1.getTaskCredentialDatabase; } });
+Object.defineProperty(exports, "resolveTaskCredentialDatabaseUrl", { enumerable: true, get: function () { return TaskCredentialDatabase_1.resolveTaskCredentialDatabaseUrl; } });
+Object.defineProperty(exports, "resetTaskCredentialDatabases", { enumerable: true, get: function () { return TaskCredentialDatabase_1.resetTaskCredentialDatabases; } });
+var TaskCredentialStore_1 = require("./TaskCredentialStore");
+Object.defineProperty(exports, "TASK_CREDENTIAL_ENCRYPTION_FAILED", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_ENCRYPTION_FAILED; } });
+Object.defineProperty(exports, "TASK_CREDENTIAL_NOT_ACTIVE", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_NOT_ACTIVE; } });
+Object.defineProperty(exports, "TASK_CREDENTIAL_NOT_FOUND", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_NOT_FOUND; } });
+Object.defineProperty(exports, "TASK_CREDENTIAL_OWNER_MISMATCH", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_OWNER_MISMATCH; } });
+Object.defineProperty(exports, "TASK_CREDENTIAL_VERSION_CONFLICT", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_VERSION_CONFLICT; } });
+Object.defineProperty(exports, "TaskCredentialStore", { enumerable: true, get: function () { return TaskCredentialStore_1.TaskCredentialStore; } });
+var TaskCredentialSchema_1 = require("./TaskCredentialSchema");
+Object.defineProperty(exports, "ensureTaskCredentialTables", { enumerable: true, get: function () { return TaskCredentialSchema_1.ensureTaskCredentialTables; } });
+Object.defineProperty(exports, "taskCredentialSchema", { enumerable: true, get: function () { return TaskCredentialSchema_1.taskCredentialSchema; } });
+Object.defineProperty(exports, "taskCredentialsPg", { enumerable: true, get: function () { return TaskCredentialSchema_1.taskCredentialsPg; } });
+Object.defineProperty(exports, "taskCredentialsSqlite", { enumerable: true, get: function () { return TaskCredentialSchema_1.taskCredentialsSqlite; } });
 var TaskAuthBinding_1 = require("./TaskAuthBinding");
 Object.defineProperty(exports, "TASK_AUTH_CREDENTIAL_SERVICE", { enumerable: true, get: function () { return TaskAuthBinding_1.TASK_AUTH_CREDENTIAL_SERVICE; } });
 Object.defineProperty(exports, "TaskAuthBindingKind", { enumerable: true, get: function () { return TaskAuthBinding_1.TaskAuthBindingKind; } });

package/dist/cli/commands/start.d.ts

@@ -13,26 +13,19 @@ export declare const startCommand: CommandModule<object, StartArgs>;
 /**
  * Where remote-forwarded traffic lands on this machine.
  *
- * Order: explicit `XPOD_GATEWAY_INGRESS_PORT` → the active SakuraFrp tunnel's assigned local
- * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
- * forwards to a specific port cannot follow us somewhere else.
+ * The decision (explicit pin → the active profile's console declaration → the gateway-derived
+ * entry) lives in `src/runtime/ingress-port.ts`, together with the strict "taken means taken"
+ * check and the occupant naming. This only reports the outcome, so the startup banner says
+ * whether the entry was pinned, adopted from a console, or derived from the gateway port.
  */
-/**
- * The port a remote tunnel forwards to: the Gateway's tunnel entry.
- *
- * It is derived from the Gateway port by the same rule the runtime uses, so the CLI can hand
- * it to the managed edge agent before the runtime binds it. A console that forwards somewhere
- * else is a mismatch the tunnel provider reports from its own read-back - the runtime never
- * moves its gate to match a console.
- */
-export declare function resolveIngressPort(provisionedConfig: {
-    tunnelProfiles?: Array<{
-        id: string;
+export declare function describeIngressDecision(ingress: {
+    port: number;
+    source: string;
+    declared?: {
         provider: string;
-        credentialEnvKey?: string;
-    }>;
-    tunnelActiveProfileId?: string;
-}, mainPort: number): Promise<number>;
+        readBack: string;
+    };
+}): string;
 export declare function resolveCliOidcIssuer(env: Record<string, string | undefined>, provisionedIssuer?: string, edition?: string): string | undefined;
 export declare function resolveManagedEdgeAgentConfig(config: Pick<ReturnType<typeof loadConfigFromEnv>, 'cloudApiEndpoint' | 'nodeId' | 'nodeToken'>, gatewayPort: number, ingressPort?: number, runtimeEnv?: Record<string, string | undefined>): {
     signalEndpoint: string;