@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/sync/coordinator/workspaceSyncCloudCredentialValidator.d.ts

@@ -0,0 +1,19 @@
+import type { WorkspaceSyncCredentialValidation } from './workspaceSyncCredentialBroker.js';
+export declare class WorkspaceSyncCloudCredentialValidatorError extends Error {
+    readonly code: 'SYNC_COORDINATOR_AUTH_INVALID' | 'SYNC_COORDINATOR_AUTH_UNAVAILABLE' | 'SYNC_COORDINATOR_ACCESS_BOOTSTRAP_UNAVAILABLE';
+    constructor(message: string, code: 'SYNC_COORDINATOR_AUTH_INVALID' | 'SYNC_COORDINATOR_AUTH_UNAVAILABLE' | 'SYNC_COORDINATOR_ACCESS_BOOTSTRAP_UNAVAILABLE');
+}
+export declare function createWorkspaceSyncCloudCredentialValidator(options: {
+    cloudBaseUrl: string;
+    tenantId: string;
+    fetchImpl?: typeof fetch;
+    cloudflareAccess?: {
+        clientId: string;
+        clientSecret: string;
+    } | null;
+    timeoutMs?: number;
+    onValidated?: (validation: WorkspaceSyncCredentialValidation) => Promise<void> | void;
+}): (input: {
+    cookieHeader: string;
+    workspaceId: string;
+}) => Promise<WorkspaceSyncCredentialValidation>;

package/dist/sync/coordinator/workspaceSyncCloudCredentialValidator.js

@@ -0,0 +1,83 @@
+import { createHash } from 'crypto';
+export class WorkspaceSyncCloudCredentialValidatorError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkspaceSyncCloudCredentialValidatorError';
+    }
+}
+export function createWorkspaceSyncCloudCredentialValidator(options) {
+    const cloudBaseUrl = String(options.cloudBaseUrl || '').trim().replace(/\/+$/, '');
+    if (!/^https?:\/\//i.test(cloudBaseUrl)) {
+        return async () => {
+            throw new WorkspaceSyncCloudCredentialValidatorError('The Taskforce cloud session validator is unavailable.', 'SYNC_COORDINATOR_AUTH_UNAVAILABLE');
+        };
+    }
+    return async (input) => {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 15_000);
+        timeout.unref?.();
+        try {
+            const headers = new Headers({
+                Accept: 'application/json',
+                Cookie: input.cookieHeader,
+            });
+            if (options.cloudflareAccess?.clientId && options.cloudflareAccess.clientSecret) {
+                headers.set('CF-Access-Client-Id', options.cloudflareAccess.clientId);
+                headers.set('CF-Access-Client-Secret', options.cloudflareAccess.clientSecret);
+            }
+            const response = await (options.fetchImpl || fetch)(`${cloudBaseUrl}/api/taskforce/auth/session`, {
+                method: 'GET',
+                headers,
+                redirect: 'manual',
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new WorkspaceSyncCloudCredentialValidatorError(response.status === 401 || response.status === 403
+                    ? 'The Taskforce cloud session is no longer authorized.'
+                    : 'Taskforce cloud session validation is temporarily unavailable.', response.status === 401 || response.status === 403
+                    ? 'SYNC_COORDINATOR_AUTH_INVALID'
+                    : 'SYNC_COORDINATOR_AUTH_UNAVAILABLE');
+            }
+            const payload = await response.json();
+            const userId = String(payload.userId || '').trim();
+            const workspaceId = String(payload.workspaceId || '').trim();
+            const role = String(payload.role || '').trim();
+            if (payload.authenticated !== true
+                || !userId
+                || userId === 'anonymous'
+                || workspaceId !== input.workspaceId
+                || !role
+                || payload.workspaceAccessActive !== true
+                || payload.accountDisabled === true
+                || payload.workspaceDisabled === true) {
+                throw new WorkspaceSyncCloudCredentialValidatorError('The Taskforce cloud session is not valid for the active workspace.', 'SYNC_COORDINATOR_AUTH_INVALID');
+            }
+            const validation = {
+                principal: {
+                    userId,
+                    tenantId: options.tenantId,
+                },
+                workspaceId,
+                role,
+                sessionId: createHash('sha256').update(input.cookieHeader).digest('hex'),
+            };
+            try {
+                await options.onValidated?.(validation);
+            }
+            catch {
+                throw new WorkspaceSyncCloudCredentialValidatorError('The verified cloud workspace access could not be projected locally.', 'SYNC_COORDINATOR_ACCESS_BOOTSTRAP_UNAVAILABLE');
+            }
+            return validation;
+        }
+        catch (error) {
+            if (error instanceof WorkspaceSyncCloudCredentialValidatorError)
+                throw error;
+            throw new WorkspaceSyncCloudCredentialValidatorError('Taskforce cloud session validation is temporarily unavailable.', 'SYNC_COORDINATOR_AUTH_UNAVAILABLE');
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    };
+}

package/dist/sync/coordinator/workspaceSyncCredentialBroker.d.ts

@@ -0,0 +1,117 @@
+import type { LocalSyncCoordinatorPrincipal } from './localSyncCoordinatorTypes.js';
+export interface WorkspaceSyncCredentialValidation {
+    principal: LocalSyncCoordinatorPrincipal;
+    workspaceId: string;
+    role: string;
+    sessionId: string;
+    expiresAt?: string | null;
+}
+export interface WorkspaceSyncCredentialSnapshot {
+    status: 'blocked-auth' | 'ready';
+    workspaceId: string | null;
+    coordinatorGeneration: number | null;
+    principal: LocalSyncCoordinatorPrincipal | null;
+    role: string | null;
+    sessionId: string | null;
+    expiresAt: string | null;
+    blockedReason: string | null;
+}
+type BoundCapability = WorkspaceSyncCredentialValidation & {
+    coordinatorGeneration: number;
+    cookieHeader: string;
+    authorizedCookies: Map<string, WorkspaceSyncCredentialValidation>;
+};
+/**
+ * Memory-only credential candidate for one authoritative workspace switch.
+ * This object must never be serialized, logged, or persisted.
+ */
+export type PreparedWorkspaceSyncCredentialSwitch = {
+    sourceWorkspaceId: string;
+    sourceCoordinatorGeneration: number;
+    targetWorkspaceId: string;
+    targetCoordinatorGeneration: number;
+    principal: WorkspaceSyncCredentialValidation['principal'];
+    cookieHeader: string;
+    validation: WorkspaceSyncCredentialValidation;
+    sourceCapability: BoundCapability;
+    activated: boolean;
+};
+export declare class WorkspaceSyncCredentialBrokerError extends Error {
+    readonly code: 'SYNC_COORDINATOR_AUTH_REQUIRED' | 'SYNC_COORDINATOR_AUTH_INVALID' | 'SYNC_COORDINATOR_PRINCIPAL_CONFLICT' | 'SYNC_COORDINATOR_INACTIVE_WORKSPACE' | 'SYNC_COORDINATOR_STALE_GENERATION';
+    constructor(message: string, code: 'SYNC_COORDINATOR_AUTH_REQUIRED' | 'SYNC_COORDINATOR_AUTH_INVALID' | 'SYNC_COORDINATOR_PRINCIPAL_CONFLICT' | 'SYNC_COORDINATOR_INACTIVE_WORKSPACE' | 'SYNC_COORDINATOR_STALE_GENERATION');
+}
+export declare class WorkspaceSyncCredentialBroker {
+    private readonly options;
+    private capability;
+    private blockedReason;
+    constructor(options: {
+        sessionCookieName: string;
+        validate: (input: {
+            cookieHeader: string;
+            workspaceId: string;
+        }) => Promise<WorkspaceSyncCredentialValidation>;
+        now?: () => Date;
+    });
+    bindFromCookieHeader(input: {
+        cookieHeader: string | undefined;
+        workspaceId: string;
+        coordinatorGeneration: number;
+        allowPrincipalRebind?: boolean;
+    }): Promise<WorkspaceSyncCredentialSnapshot>;
+    rotateFromSetCookieHeaders(input: {
+        setCookieHeaders: readonly string[];
+        workspaceId: string;
+        coordinatorGeneration: number;
+    }): Promise<{
+        snapshot: WorkspaceSyncCredentialSnapshot;
+        setCookieHeader: string;
+    }>;
+    prepareWorkspaceSwitch(input: {
+        cookieHeader: string | undefined;
+        expectedSourceWorkspaceId: string;
+        sourceCoordinatorGeneration: number;
+        targetWorkspaceId: string;
+        targetCoordinatorGeneration: number;
+    }): Promise<PreparedWorkspaceSyncCredentialSwitch>;
+    commitPreparedWorkspaceSwitch(prepared: PreparedWorkspaceSyncCredentialSwitch): WorkspaceSyncCredentialSnapshot;
+    rollbackPreparedWorkspaceSwitch(prepared: PreparedWorkspaceSyncCredentialSwitch, coordinatorGeneration?: number): WorkspaceSyncCredentialSnapshot;
+    advanceCoordinatorGeneration(input: {
+        cookieHeader: string | undefined;
+        workspaceId: string;
+        fromCoordinatorGeneration: number;
+        toCoordinatorGeneration: number;
+    }): WorkspaceSyncCredentialSnapshot;
+    /**
+     * Advances the in-memory capability alongside an exact coordinator ownership
+     * transfer. This is an internal server lifecycle seam; browser callers must
+     * use the cookie-authorized generation transition above.
+     */
+    advanceCoordinatorGenerationForOwnershipTransfer(input: {
+        workspaceId: string;
+        fromCoordinatorGeneration: number;
+        toCoordinatorGeneration: number;
+    }): WorkspaceSyncCredentialSnapshot;
+    authorizeCookieHeader(input: {
+        cookieHeader: string | undefined;
+        workspaceId: string;
+        coordinatorGeneration: number;
+    }): void;
+    clearFromCookieHeader(input: {
+        cookieHeader: string | undefined;
+        workspaceId: string;
+        coordinatorGeneration: number;
+        reason?: string;
+    }): WorkspaceSyncCredentialSnapshot;
+    requireCapability(input: {
+        workspaceId: string;
+        coordinatorGeneration: number;
+    }): {
+        cookieHeader: string;
+        validation: WorkspaceSyncCredentialValidation;
+    };
+    clear(reason?: string): void;
+    handleUpstreamStatus(status: number): void;
+    readSnapshot(): WorkspaceSyncCredentialSnapshot;
+    private now;
+}
+export {};

package/dist/sync/coordinator/workspaceSyncCredentialBroker.js

@@ -0,0 +1,323 @@
+import { timingSafeEqual } from 'crypto';
+import { findSetCookieHeader } from '../../utils/httpSetCookie.js';
+const MAX_AUTHORIZED_BROWSER_SESSIONS = 16;
+export class WorkspaceSyncCredentialBrokerError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkspaceSyncCredentialBrokerError';
+    }
+}
+export class WorkspaceSyncCredentialBroker {
+    options;
+    capability = null;
+    blockedReason = 'server-restart';
+    constructor(options) {
+        this.options = options;
+    }
+    async bindFromCookieHeader(input) {
+        const cookieValue = extractCookie(input.cookieHeader, this.options.sessionCookieName);
+        if (!cookieValue) {
+            throw new WorkspaceSyncCredentialBrokerError('An authenticated Taskforce session is required to attach cloud sync.', 'SYNC_COORDINATOR_AUTH_REQUIRED');
+        }
+        const cookieHeader = `${this.options.sessionCookieName}=${cookieValue}`;
+        let validated;
+        try {
+            validated = await this.options.validate({
+                cookieHeader,
+                workspaceId: input.workspaceId,
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+        if (!validated.sessionId
+            || !validated.principal.userId
+            || !validated.principal.tenantId
+            || validated.workspaceId !== input.workspaceId) {
+            throw new WorkspaceSyncCredentialBrokerError('The Taskforce session is not valid for the requested workspace.', 'SYNC_COORDINATOR_AUTH_INVALID');
+        }
+        const existing = this.capability;
+        const samePrincipal = existing
+            && existing.workspaceId === validated.workspaceId
+            && existing.principal.userId === validated.principal.userId
+            && existing.principal.tenantId === validated.principal.tenantId;
+        if (existing && !samePrincipal && !input.allowPrincipalRebind) {
+            throw new WorkspaceSyncCredentialBrokerError('A different Taskforce principal is already bound to this workspace coordinator.', 'SYNC_COORDINATOR_PRINCIPAL_CONFLICT');
+        }
+        if (samePrincipal
+            && input.coordinatorGeneration < existing.coordinatorGeneration) {
+            throw new WorkspaceSyncCredentialBrokerError(`Coordinator generation ${input.coordinatorGeneration} is stale; current generation is ${existing.coordinatorGeneration}.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        const authorizedCookies = samePrincipal
+            ? new Map(existing.authorizedCookies)
+            : new Map();
+        authorizedCookies.delete(cookieValue);
+        authorizedCookies.set(cookieValue, validated);
+        while (authorizedCookies.size > MAX_AUTHORIZED_BROWSER_SESSIONS) {
+            const oldestCookieValue = authorizedCookies.keys().next().value;
+            if (!oldestCookieValue)
+                break;
+            authorizedCookies.delete(oldestCookieValue);
+        }
+        this.capability = {
+            ...validated,
+            coordinatorGeneration: input.coordinatorGeneration,
+            cookieHeader,
+            authorizedCookies,
+        };
+        this.blockedReason = null;
+        return this.readSnapshot();
+    }
+    async rotateFromSetCookieHeaders(input) {
+        const previousCookieValue = extractCookie(this.capability?.cookieHeader, this.options.sessionCookieName);
+        const setCookieHeader = findSetCookieHeader(input.setCookieHeaders, this.options.sessionCookieName);
+        if (!setCookieHeader) {
+            throw new WorkspaceSyncCredentialBrokerError('Cloud workspace provisioning did not return a replacement Taskforce session.', 'SYNC_COORDINATOR_AUTH_INVALID');
+        }
+        const snapshot = await this.bindFromCookieHeader({
+            cookieHeader: setCookieHeader,
+            workspaceId: input.workspaceId,
+            coordinatorGeneration: input.coordinatorGeneration,
+        });
+        const rotatedCookieValue = extractCookie(setCookieHeader, this.options.sessionCookieName);
+        if (previousCookieValue
+            && rotatedCookieValue
+            && !safeStringEqual(previousCookieValue, rotatedCookieValue)) {
+            this.capability?.authorizedCookies.delete(previousCookieValue);
+        }
+        return { snapshot, setCookieHeader };
+    }
+    async prepareWorkspaceSwitch(input) {
+        const source = this.requireCapability({
+            workspaceId: input.expectedSourceWorkspaceId,
+            coordinatorGeneration: input.sourceCoordinatorGeneration,
+        });
+        if (input.targetCoordinatorGeneration !== input.sourceCoordinatorGeneration + 1) {
+            throw new WorkspaceSyncCredentialBrokerError('The workspace-switch coordinator generation is stale or non-adjacent.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        const cookieValue = extractCookie(input.cookieHeader, this.options.sessionCookieName);
+        if (!cookieValue) {
+            throw new WorkspaceSyncCredentialBrokerError('An authenticated Taskforce session is required for the target workspace.', 'SYNC_COORDINATOR_AUTH_REQUIRED');
+        }
+        const cookieHeader = `${this.options.sessionCookieName}=${cookieValue}`;
+        const validation = await this.options.validate({
+            cookieHeader,
+            workspaceId: input.targetWorkspaceId,
+        });
+        if (!validation.sessionId
+            || validation.workspaceId !== input.targetWorkspaceId
+            || validation.principal.userId !== source.validation.principal.userId
+            || validation.principal.tenantId !== source.validation.principal.tenantId) {
+            throw new WorkspaceSyncCredentialBrokerError('The target workspace session belongs to a different Taskforce principal.', 'SYNC_COORDINATOR_PRINCIPAL_CONFLICT');
+        }
+        const capability = this.capability;
+        return {
+            sourceWorkspaceId: input.expectedSourceWorkspaceId,
+            sourceCoordinatorGeneration: input.sourceCoordinatorGeneration,
+            targetWorkspaceId: input.targetWorkspaceId,
+            targetCoordinatorGeneration: input.targetCoordinatorGeneration,
+            principal: validation.principal,
+            cookieHeader,
+            validation,
+            sourceCapability: {
+                ...capability,
+                authorizedCookies: new Map(capability.authorizedCookies),
+            },
+            activated: false,
+        };
+    }
+    commitPreparedWorkspaceSwitch(prepared) {
+        this.requireCapability({
+            workspaceId: prepared.sourceWorkspaceId,
+            coordinatorGeneration: prepared.sourceCoordinatorGeneration,
+        });
+        if (prepared.activated) {
+            throw new WorkspaceSyncCredentialBrokerError('The target workspace credential was already activated.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        const cookieValue = extractCookie(prepared.cookieHeader, this.options.sessionCookieName);
+        this.capability = {
+            ...prepared.validation,
+            coordinatorGeneration: prepared.targetCoordinatorGeneration,
+            cookieHeader: prepared.cookieHeader,
+            authorizedCookies: new Map([[cookieValue, prepared.validation]]),
+        };
+        prepared.activated = true;
+        this.blockedReason = null;
+        return this.readSnapshot();
+    }
+    rollbackPreparedWorkspaceSwitch(prepared, coordinatorGeneration = prepared.sourceCoordinatorGeneration) {
+        const current = this.capability;
+        const stillOwnsSourceCapability = current
+            && current.workspaceId === prepared.sourceWorkspaceId
+            && current.coordinatorGeneration === prepared.sourceCoordinatorGeneration
+            && current.sessionId === prepared.sourceCapability.sessionId;
+        if (prepared.activated || stillOwnsSourceCapability) {
+            this.capability = {
+                ...prepared.sourceCapability,
+                coordinatorGeneration,
+                authorizedCookies: new Map(prepared.sourceCapability.authorizedCookies),
+            };
+            prepared.activated = false;
+            this.blockedReason = null;
+        }
+        return this.readSnapshot();
+    }
+    advanceCoordinatorGeneration(input) {
+        this.authorizeCookieHeader({
+            cookieHeader: input.cookieHeader,
+            workspaceId: input.workspaceId,
+            coordinatorGeneration: input.fromCoordinatorGeneration,
+        });
+        if (!Number.isInteger(input.toCoordinatorGeneration)
+            || input.toCoordinatorGeneration <= input.fromCoordinatorGeneration) {
+            throw new WorkspaceSyncCredentialBrokerError('The coordinator generation transition is invalid.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        this.capability.coordinatorGeneration = input.toCoordinatorGeneration;
+        return this.readSnapshot();
+    }
+    /**
+     * Advances the in-memory capability alongside an exact coordinator ownership
+     * transfer. This is an internal server lifecycle seam; browser callers must
+     * use the cookie-authorized generation transition above.
+     */
+    advanceCoordinatorGenerationForOwnershipTransfer(input) {
+        const capability = this.capability;
+        if (!capability) {
+            throw new WorkspaceSyncCredentialBrokerError('Cloud sync is blocked until an authenticated Taskforce window reconnects.', 'SYNC_COORDINATOR_AUTH_REQUIRED');
+        }
+        if (capability.workspaceId !== input.workspaceId) {
+            throw new WorkspaceSyncCredentialBrokerError('The attached Taskforce session belongs to a different workspace.', 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+        }
+        if (!Number.isInteger(input.fromCoordinatorGeneration)
+            || capability.coordinatorGeneration !== input.fromCoordinatorGeneration
+            || !Number.isInteger(input.toCoordinatorGeneration)
+            || input.toCoordinatorGeneration !== input.fromCoordinatorGeneration + 1) {
+            throw new WorkspaceSyncCredentialBrokerError('The coordinator generation transition is stale or non-adjacent.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        capability.coordinatorGeneration = input.toCoordinatorGeneration;
+        return this.readSnapshot();
+    }
+    authorizeCookieHeader(input) {
+        this.requireCapability(input);
+        const capability = this.capability;
+        const cookieValue = extractCookie(input.cookieHeader, this.options.sessionCookieName);
+        const authorized = cookieValue
+            ? findSafeStringMapValue(capability.authorizedCookies, cookieValue)
+            : null;
+        if (!authorized) {
+            throw new WorkspaceSyncCredentialBrokerError('This browser session does not own the attached sync capability.', 'SYNC_COORDINATOR_PRINCIPAL_CONFLICT');
+        }
+        if (authorized.expiresAt
+            && new Date(authorized.expiresAt).getTime() <= this.now().getTime()) {
+            capability.authorizedCookies.delete(cookieValue);
+            throw new WorkspaceSyncCredentialBrokerError('This browser session has expired.', 'SYNC_COORDINATOR_AUTH_REQUIRED');
+        }
+    }
+    clearFromCookieHeader(input) {
+        this.authorizeCookieHeader(input);
+        const cookieValue = extractCookie(input.cookieHeader, this.options.sessionCookieName);
+        const capability = this.capability;
+        const remaining = new Map([...capability.authorizedCookies]
+            .filter(([value]) => !safeStringEqual(value, cookieValue)));
+        if (remaining.size === 0) {
+            this.clear(input.reason || 'logout');
+        }
+        else {
+            capability.authorizedCookies = remaining;
+            if (!findSafeStringMapValue(remaining, extractCookie(capability.cookieHeader, this.options.sessionCookieName) || '')) {
+                const [nextCookieValue, nextValidation] = remaining.entries().next().value;
+                capability.cookieHeader = `${this.options.sessionCookieName}=${nextCookieValue}`;
+                Object.assign(capability, nextValidation);
+            }
+        }
+        return this.readSnapshot();
+    }
+    requireCapability(input) {
+        const capability = this.capability;
+        if (!capability) {
+            throw new WorkspaceSyncCredentialBrokerError('Cloud sync is blocked until an authenticated Taskforce window reconnects.', 'SYNC_COORDINATOR_AUTH_REQUIRED');
+        }
+        if (capability.coordinatorGeneration !== input.coordinatorGeneration) {
+            throw new WorkspaceSyncCredentialBrokerError('The attached Taskforce session belongs to a stale coordinator generation.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        if (capability.workspaceId !== input.workspaceId) {
+            throw new WorkspaceSyncCredentialBrokerError('The attached Taskforce session belongs to a different workspace.', 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+        }
+        if (capability.expiresAt && new Date(capability.expiresAt).getTime() <= this.now().getTime()) {
+            this.clear('session-expired');
+            throw new WorkspaceSyncCredentialBrokerError('The attached Taskforce session has expired.', 'SYNC_COORDINATOR_AUTH_REQUIRED');
+        }
+        return {
+            cookieHeader: capability.cookieHeader,
+            validation: {
+                principal: capability.principal,
+                workspaceId: capability.workspaceId,
+                role: capability.role,
+                sessionId: capability.sessionId,
+                expiresAt: capability.expiresAt,
+            },
+        };
+    }
+    clear(reason = 'logout') {
+        this.capability = null;
+        this.blockedReason = reason;
+    }
+    handleUpstreamStatus(status) {
+        if (status === 401 || status === 403)
+            this.clear(`cloud-${status}`);
+    }
+    readSnapshot() {
+        const capability = this.capability;
+        return capability ? {
+            status: 'ready',
+            workspaceId: capability.workspaceId,
+            coordinatorGeneration: capability.coordinatorGeneration,
+            principal: capability.principal,
+            role: capability.role,
+            sessionId: capability.sessionId,
+            expiresAt: capability.expiresAt || null,
+            blockedReason: null,
+        } : {
+            status: 'blocked-auth',
+            workspaceId: null,
+            coordinatorGeneration: null,
+            principal: null,
+            role: null,
+            sessionId: null,
+            expiresAt: null,
+            blockedReason: this.blockedReason,
+        };
+    }
+    now() {
+        return this.options.now?.() || new Date();
+    }
+}
+function extractCookie(rawHeader, cookieName) {
+    if (!rawHeader || !cookieName)
+        return null;
+    for (const pair of rawHeader.split(';')) {
+        const separator = pair.indexOf('=');
+        if (separator <= 0)
+            continue;
+        if (pair.slice(0, separator).trim() !== cookieName)
+            continue;
+        const value = pair.slice(separator + 1).trim();
+        return value || null;
+    }
+    return null;
+}
+function safeStringEqual(left, right) {
+    const leftBytes = Buffer.from(left);
+    const rightBytes = Buffer.from(right);
+    return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+function findSafeStringMapValue(values, candidate) {
+    let matched = null;
+    for (const [value, entry] of values) {
+        if (safeStringEqual(value, candidate))
+            matched = entry;
+    }
+    return matched;
+}

package/dist/sync/coordinator/workspaceSyncLocalAccessBootstrap.d.ts

@@ -0,0 +1,11 @@
+import type { TaskforceCore } from '../../core/Taskforce.js';
+import type { WorkspaceSyncCredentialValidation } from './workspaceSyncCredentialBroker.js';
+export declare class WorkspaceSyncLocalAccessBootstrapError extends Error {
+    constructor(message: string);
+}
+/**
+ * Projects one cloud-verified workspace principal into the local authorization
+ * tables required by server-owned sync. The caller must supply the result of
+ * the fixed cloud session validator; request-body claims are not accepted.
+ */
+export declare function bootstrapVerifiedWorkspaceSyncAccess(core: Pick<TaskforceCore, 'ensureBootstrapUserAccess' | 'getDatabaseAdapter' | 'getTenantId'>, validation: WorkspaceSyncCredentialValidation): void;

package/dist/sync/coordinator/workspaceSyncLocalAccessBootstrap.js

@@ -0,0 +1,51 @@
+const VERIFIED_WORKSPACE_ROLES = new Set([
+    'owner',
+    'admin',
+    'member',
+    'read-only',
+]);
+export class WorkspaceSyncLocalAccessBootstrapError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorkspaceSyncLocalAccessBootstrapError';
+    }
+}
+/**
+ * Projects one cloud-verified workspace principal into the local authorization
+ * tables required by server-owned sync. The caller must supply the result of
+ * the fixed cloud session validator; request-body claims are not accepted.
+ */
+export function bootstrapVerifiedWorkspaceSyncAccess(core, validation) {
+    const workspaceId = String(validation.workspaceId || '').trim();
+    const userId = String(validation.principal?.userId || '').trim();
+    const tenantId = String(validation.principal?.tenantId || '').trim();
+    const role = String(validation.role || '').trim().toLowerCase();
+    if (!workspaceId
+        || workspaceId === 'default'
+        || !userId
+        || !tenantId
+        || tenantId !== core.getTenantId()
+        || !VERIFIED_WORKSPACE_ROLES.has(role)) {
+        throw new WorkspaceSyncLocalAccessBootstrapError('The verified cloud workspace principal cannot be projected locally.');
+    }
+    const transaction = core.getDatabaseAdapter().transaction(() => {
+        core.ensureBootstrapUserAccess({
+            userId,
+            workspaceId,
+            role,
+        });
+        const now = new Date().toISOString();
+        const permissionMode = role === 'read-only' ? 'read-only' : 'read-write';
+        core.getDatabaseAdapter().prepare(`
+            UPDATE users
+            SET is_disabled = 0, updated_at = ?
+            WHERE tenant_id = ? AND id = ?
+        `).run(now, tenantId, userId);
+        core.getDatabaseAdapter().prepare(`
+            UPDATE workspace_memberships
+            SET role = ?, status = 'active', permission_mode = ?, updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND user_id = ?
+        `).run(role, permissionMode, now, tenantId, workspaceId, userId);
+    });
+    transaction();
+}