@exaudeus/workrail 0.9.0 → 0.11.0

package/dist/v2/durable-core/tokens/token-codec.d.ts

@@ -0,0 +1,31 @@
+import type { Result } from 'neverthrow';
+import type { CanonicalBytes } from '../ids/index.js';
+import type { TokenStringV1 } from '../ids/index.js';
+import { type TokenPayloadV1, type TokenPrefixV1 } from './payloads.js';
+export type TokenDecodeErrorV2 = {
+    readonly code: 'TOKEN_INVALID_FORMAT';
+    readonly message: string;
+} | {
+    readonly code: 'TOKEN_UNSUPPORTED_VERSION';
+    readonly message: string;
+} | {
+    readonly code: 'TOKEN_SCOPE_MISMATCH';
+    readonly message: string;
+} | {
+    readonly code: 'TOKEN_PAYLOAD_INVALID';
+    readonly message: string;
+};
+export interface ParsedTokenV1 {
+    readonly prefix: TokenPrefixV1;
+    readonly version: 1;
+    readonly payloadBase64Url: string;
+    readonly sigBase64Url: string;
+    readonly payloadBytes: CanonicalBytes;
+    readonly payload: TokenPayloadV1;
+}
+export declare function encodeTokenPayloadV1(payload: TokenPayloadV1): Result<CanonicalBytes, TokenDecodeErrorV2>;
+export declare function encodeUnsignedTokenV1(payload: TokenPayloadV1): Result<{
+    readonly token: TokenStringV1;
+    readonly payloadBytes: CanonicalBytes;
+}, TokenDecodeErrorV2>;
+export declare function parseTokenV1(token: string): Result<ParsedTokenV1, TokenDecodeErrorV2>;

package/dist/v2/durable-core/tokens/token-codec.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeTokenPayloadV1 = encodeTokenPayloadV1;
+exports.encodeUnsignedTokenV1 = encodeUnsignedTokenV1;
+exports.parseTokenV1 = parseTokenV1;
+const neverthrow_1 = require("neverthrow");
+const jcs_js_1 = require("../canonical/jcs.js");
+const index_js_1 = require("../ids/index.js");
+const base64url_js_1 = require("./base64url.js");
+const payloads_js_1 = require("./payloads.js");
+function encodeTokenPayloadV1(payload) {
+    return (0, jcs_js_1.toCanonicalBytes)(payload).mapErr((e) => ({
+        code: 'TOKEN_PAYLOAD_INVALID',
+        message: e.message,
+    }));
+}
+function encodeUnsignedTokenV1(payload) {
+    const bytes = encodeTokenPayloadV1(payload);
+    if (bytes.isErr())
+        return (0, neverthrow_1.err)(bytes.error);
+    const prefix = (0, payloads_js_1.expectedPrefixForTokenKind)(payload.tokenKind);
+    const token = `${prefix}.v1.${(0, base64url_js_1.encodeBase64Url)(bytes.value)}.`;
+    return (0, neverthrow_1.ok)({ token: (0, index_js_1.asTokenStringV1)(token), payloadBytes: bytes.value });
+}
+function parseTokenV1(token) {
+    const parts = token.split('.');
+    if (parts.length !== 4)
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: 'Expected 4 dot-separated segments' });
+    const [prefix, versionPart, payloadB64, sigB64] = parts;
+    if (versionPart !== 'v1')
+        return (0, neverthrow_1.err)({ code: 'TOKEN_UNSUPPORTED_VERSION', message: `Unsupported token version: ${versionPart}` });
+    if (prefix !== 'st' && prefix !== 'ack' && prefix !== 'chk') {
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: `Unknown token prefix: ${prefix}` });
+    }
+    if (payloadB64.trim() === '' || sigB64.trim() === '') {
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: 'Missing payload or signature segment' });
+    }
+    const decoded = (0, base64url_js_1.decodeBase64Url)(payloadB64);
+    if (decoded.isErr())
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: decoded.error.message });
+    const payloadBytes = (0, index_js_1.asCanonicalBytes)(decoded.value);
+    let payloadJson;
+    try {
+        payloadJson = JSON.parse(new TextDecoder().decode(payloadBytes));
+    }
+    catch {
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: 'Payload is not valid JSON' });
+    }
+    const validated = payloads_js_1.TokenPayloadV1Schema.safeParse(payloadJson);
+    if (!validated.success)
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: 'Token payload failed schema validation' });
+    const expectedPrefix = (0, payloads_js_1.expectedPrefixForTokenKind)(validated.data.tokenKind);
+    if (expectedPrefix !== prefix) {
+        return (0, neverthrow_1.err)({ code: 'TOKEN_SCOPE_MISMATCH', message: 'Token prefix does not match payload tokenKind' });
+    }
+    return (0, neverthrow_1.ok)({
+        prefix,
+        version: 1,
+        payloadBase64Url: payloadB64,
+        sigBase64Url: sigB64,
+        payloadBytes,
+        payload: validated.data,
+    });
+}

package/dist/v2/durable-core/tokens/token-signer.d.ts

@@ -0,0 +1,15 @@
+import type { Result } from 'neverthrow';
+import type { HmacSha256PortV2 } from '../../ports/hmac-sha256.port.js';
+import type { KeyringV1 } from '../../ports/keyring.port.js';
+import type { CanonicalBytes, TokenStringV1 } from '../ids/index.js';
+import type { ParsedTokenV1, TokenDecodeErrorV2 } from './token-codec.js';
+export type TokenVerifyErrorV2 = {
+    readonly code: 'TOKEN_BAD_SIGNATURE';
+    readonly message: string;
+} | {
+    readonly code: 'TOKEN_INVALID_FORMAT';
+    readonly message: string;
+};
+export declare function signTokenV1(unsignedTokenPrefix: 'st.v1.' | 'ack.v1.' | 'chk.v1.', payloadBytes: CanonicalBytes, keyring: KeyringV1, hmac: HmacSha256PortV2): Result<TokenStringV1, TokenVerifyErrorV2>;
+export declare function verifyTokenSignatureV1(parsed: ParsedTokenV1, keyring: KeyringV1, hmac: HmacSha256PortV2): Result<void, TokenVerifyErrorV2>;
+export declare function assertTokenScopeMatchesState(state: ParsedTokenV1, other: ParsedTokenV1): Result<void, TokenDecodeErrorV2>;

package/dist/v2/durable-core/tokens/token-signer.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signTokenV1 = signTokenV1;
+exports.verifyTokenSignatureV1 = verifyTokenSignatureV1;
+exports.assertTokenScopeMatchesState = assertTokenScopeMatchesState;
+const neverthrow_1 = require("neverthrow");
+const base64url_js_1 = require("./base64url.js");
+const index_js_1 = require("../ids/index.js");
+function decodeKeyBytes(keyBase64Url) {
+    const decoded = (0, base64url_js_1.decodeBase64Url)(keyBase64Url);
+    if (decoded.isErr())
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: 'Invalid key encoding' });
+    if (decoded.value.length !== 32)
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: 'Invalid key length' });
+    return (0, neverthrow_1.ok)(decoded.value);
+}
+function signTokenV1(unsignedTokenPrefix, payloadBytes, keyring, hmac) {
+    const key = decodeKeyBytes(keyring.current.keyBase64Url);
+    if (key.isErr())
+        return (0, neverthrow_1.err)(key.error);
+    const sig = hmac.hmacSha256(key.value, payloadBytes);
+    const token = `${unsignedTokenPrefix}${(0, base64url_js_1.encodeBase64Url)(payloadBytes)}.${(0, base64url_js_1.encodeBase64Url)(sig)}`;
+    return (0, neverthrow_1.ok)((0, index_js_1.asTokenStringV1)(token));
+}
+function verifyTokenSignatureV1(parsed, keyring, hmac) {
+    const sigBytes = (0, base64url_js_1.decodeBase64Url)(parsed.sigBase64Url);
+    if (sigBytes.isErr())
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: 'Invalid signature encoding' });
+    if (sigBytes.value.length !== 32)
+        return (0, neverthrow_1.err)({ code: 'TOKEN_INVALID_FORMAT', message: 'Invalid signature length' });
+    const keys = [keyring.current.keyBase64Url];
+    if (keyring.previous)
+        keys.push(keyring.previous.keyBase64Url);
+    for (const k of keys) {
+        const key = decodeKeyBytes(k);
+        if (key.isErr())
+            continue;
+        const expected = hmac.hmacSha256(key.value, parsed.payloadBytes);
+        if (hmac.timingSafeEqual(expected, sigBytes.value))
+            return (0, neverthrow_1.ok)(undefined);
+    }
+    return (0, neverthrow_1.err)({ code: 'TOKEN_BAD_SIGNATURE', message: 'Signature verification failed' });
+}
+function assertTokenScopeMatchesState(state, other) {
+    if (state.payload.tokenKind !== 'state') {
+        return (0, neverthrow_1.err)({ code: 'TOKEN_SCOPE_MISMATCH', message: 'Expected a state token for scope comparison' });
+    }
+    if (state.payload.sessionId !== other.payload.sessionId)
+        return (0, neverthrow_1.err)({ code: 'TOKEN_SCOPE_MISMATCH', message: 'sessionId mismatch' });
+    if (state.payload.runId !== other.payload.runId)
+        return (0, neverthrow_1.err)({ code: 'TOKEN_SCOPE_MISMATCH', message: 'runId mismatch' });
+    if (state.payload.nodeId !== other.payload.nodeId)
+        return (0, neverthrow_1.err)({ code: 'TOKEN_SCOPE_MISMATCH', message: 'nodeId mismatch' });
+    return (0, neverthrow_1.ok)(undefined);
+}

package/dist/v2/infra/local/data-dir/index.d.ts

@@ -3,6 +3,10 @@ export declare class LocalDataDirV2 implements DataDirPortV2 {
     private readonly env;
     constructor(env: Record<string, string | undefined>);
     private root;
+    snapshotsDir(): string;
+    snapshotPath(snapshotRef: string): string;
+    keysDir(): string;
+    keyringPath(): string;
     pinnedWorkflowsDir(): string;
     pinnedWorkflowPath(workflowHash: string): string;
     sessionsDir(): string;

package/dist/v2/infra/local/data-dir/index.js

@@ -44,6 +44,18 @@ class LocalDataDirV2 {
         const configured = this.env['WORKRAIL_DATA_DIR'];
         return configured ? configured : path.join(os.homedir(), '.workrail', 'data');
     }
+    snapshotsDir() {
+        return path.join(this.root(), 'snapshots');
+    }
+    snapshotPath(snapshotRef) {
+        return path.join(this.snapshotsDir(), `${snapshotRef}.json`);
+    }
+    keysDir() {
+        return path.join(this.root(), 'keys');
+    }
+    keyringPath() {
+        return path.join(this.keysDir(), 'keyring.json');
+    }
     pinnedWorkflowsDir() {
         return path.join(this.root(), 'workflows', 'pinned');
     }

package/dist/v2/infra/local/hmac-sha256/index.d.ts

@@ -0,0 +1,5 @@
+import type { HmacSha256PortV2 } from '../../../ports/hmac-sha256.port.js';
+export declare class NodeHmacSha256V2 implements HmacSha256PortV2 {
+    hmacSha256(key: Uint8Array, message: Uint8Array): Uint8Array;
+    timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+}

package/dist/v2/infra/local/hmac-sha256/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeHmacSha256V2 = void 0;
+const crypto_1 = require("crypto");
+class NodeHmacSha256V2 {
+    hmacSha256(key, message) {
+        const out = (0, crypto_1.createHmac)('sha256', Buffer.from(key)).update(Buffer.from(message)).digest();
+        return new Uint8Array(out);
+    }
+    timingSafeEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        return (0, crypto_1.timingSafeEqual)(Buffer.from(a), Buffer.from(b));
+    }
+}
+exports.NodeHmacSha256V2 = NodeHmacSha256V2;

package/dist/v2/infra/local/keyring/index.d.ts

@@ -0,0 +1,14 @@
+import type { ResultAsync } from 'neverthrow';
+import type { DataDirPortV2 } from '../../../ports/data-dir.port.js';
+import type { FileSystemPortV2 } from '../../../ports/fs.port.js';
+import type { KeyringError, KeyringPortV2, KeyringV1 } from '../../../ports/keyring.port.js';
+export declare class LocalKeyringV2 implements KeyringPortV2 {
+    private readonly dataDir;
+    private readonly fs;
+    constructor(dataDir: DataDirPortV2, fs: FileSystemPortV2);
+    loadOrCreate(): ResultAsync<KeyringV1, KeyringError>;
+    rotate(): ResultAsync<KeyringV1, KeyringError>;
+    private createAndPersistFresh;
+    private parseAndValidate;
+    private persist;
+}

package/dist/v2/infra/local/keyring/index.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalKeyringV2 = void 0;
+const crypto_1 = require("crypto");
+const zod_1 = require("zod");
+const neverthrow_1 = require("neverthrow");
+const jcs_js_1 = require("../../../durable-core/canonical/jcs.js");
+const KeyRecordSchema = zod_1.z.object({
+    alg: zod_1.z.literal('hmac_sha256'),
+    keyBase64Url: zod_1.z.string().min(1),
+});
+const KeyringFileV1Schema = zod_1.z.object({
+    v: zod_1.z.literal(1),
+    current: KeyRecordSchema,
+    previous: KeyRecordSchema.nullable(),
+});
+function encodeBase64Url(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+function decodeBase64Url(s) {
+    try {
+        return new Uint8Array(Buffer.from(s, 'base64url'));
+    }
+    catch {
+        return null;
+    }
+}
+function validateKeyMaterialOrThrow(keyBase64Url) {
+    const decoded = decodeBase64Url(keyBase64Url);
+    if (!decoded)
+        throw new Error('invalid_base64url');
+    if (decoded.length !== 32)
+        throw new Error('invalid_key_length');
+}
+function createFreshKeyRecord() {
+    const bytes = (0, crypto_1.randomBytes)(32);
+    return { alg: 'hmac_sha256', keyBase64Url: encodeBase64Url(bytes) };
+}
+class LocalKeyringV2 {
+    constructor(dataDir, fs) {
+        this.dataDir = dataDir;
+        this.fs = fs;
+    }
+    loadOrCreate() {
+        const path = this.dataDir.keyringPath();
+        return this.fs
+            .readFileUtf8(path)
+            .andThen((raw) => this.parseAndValidate(raw, path))
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return this.createAndPersistFresh();
+            return (0, neverthrow_1.errAsync)({ code: 'KEYRING_IO_ERROR', message: e.message });
+        });
+    }
+    rotate() {
+        return this.loadOrCreate().andThen((kr) => {
+            const next = {
+                v: 1,
+                current: createFreshKeyRecord(),
+                previous: kr.current,
+            };
+            return this.persist(next).map(() => next);
+        });
+    }
+    createAndPersistFresh() {
+        const fresh = { v: 1, current: createFreshKeyRecord(), previous: null };
+        return this.persist(fresh).map(() => fresh);
+    }
+    parseAndValidate(raw, filePath) {
+        return neverthrow_1.ResultAsync.fromPromise((async () => {
+            const parsed = JSON.parse(raw);
+            const validated = KeyringFileV1Schema.safeParse(parsed);
+            if (!validated.success)
+                throw new Error('invalid_shape');
+            validateKeyMaterialOrThrow(validated.data.current.keyBase64Url);
+            if (validated.data.previous)
+                validateKeyMaterialOrThrow(validated.data.previous.keyBase64Url);
+            return validated.data;
+        })(), () => ({ code: 'KEYRING_CORRUPTION_DETECTED', message: `Invalid keyring file: ${filePath}` }));
+    }
+    persist(keyring) {
+        const dir = this.dataDir.keysDir();
+        const filePath = this.dataDir.keyringPath();
+        const tmpPath = `${filePath}.tmp`;
+        const canonical = (0, jcs_js_1.toCanonicalBytes)(keyring).mapErr((e) => ({
+            code: 'KEYRING_INVARIANT_VIOLATION',
+            message: e.message,
+        }));
+        if (canonical.isErr())
+            return (0, neverthrow_1.errAsync)(canonical.error);
+        return this.fs
+            .mkdirp(dir)
+            .andThen(() => this.fs.openWriteTruncate(tmpPath))
+            .andThen((h) => this.fs
+            .writeAll(h.fd, canonical.value)
+            .andThen(() => this.fs.fsyncFile(h.fd))
+            .andThen(() => this.fs.closeFile(h.fd)))
+            .andThen(() => this.fs.rename(tmpPath, filePath))
+            .andThen(() => this.fs.fsyncDir(dir))
+            .mapErr((e) => ({ code: 'KEYRING_IO_ERROR', message: e.message }));
+    }
+}
+exports.LocalKeyringV2 = LocalKeyringV2;

package/dist/v2/infra/local/session-store/index.d.ts

@@ -2,20 +2,21 @@ import type { ResultAsync } from 'neverthrow';
 import type { DataDirPortV2 } from '../../../ports/data-dir.port.js';
 import type { FileSystemPortV2 } from '../../../ports/fs.port.js';
 import type { Sha256PortV2 } from '../../../ports/sha256.port.js';
-import type { SessionLockPortV2 } from '../../../ports/session-lock.port.js';
-import type { AppendPlanV2, SessionEventLogStoreError, LoadedSessionTruthV2, SessionEventLogStorePortV2 } from '../../../ports/session-event-log-store.port.js';
+import type { AppendPlanV2, LoadedValidatedPrefixV2, SessionEventLogStoreError, LoadedSessionTruthV2, SessionEventLogAppendStorePortV2, SessionEventLogReadonlyStorePortV2 } from '../../../ports/session-event-log-store.port.js';
 import type { SessionId } from '../../../durable-core/ids/index.js';
-export declare class LocalSessionEventLogStoreV2 implements SessionEventLogStorePortV2 {
+import type { WithHealthySessionLock } from '../../../durable-core/ids/with-healthy-session-lock.js';
+export declare class LocalSessionEventLogStoreV2 implements SessionEventLogReadonlyStorePortV2, SessionEventLogAppendStorePortV2 {
     private readonly dataDir;
     private readonly fs;
     private readonly sha256;
-    private readonly lock;
-    constructor(dataDir: DataDirPortV2, fs: FileSystemPortV2, sha256: Sha256PortV2, lock: SessionLockPortV2);
-    append(sessionId: SessionId, plan: AppendPlanV2): ResultAsync<void, SessionEventLogStoreError>;
+    constructor(dataDir: DataDirPortV2, fs: FileSystemPortV2, sha256: Sha256PortV2);
+    append(lock: WithHealthySessionLock, plan: AppendPlanV2): ResultAsync<void, SessionEventLogStoreError>;
     load(sessionId: SessionId): ResultAsync<LoadedSessionTruthV2, SessionEventLogStoreError>;
+    loadValidatedPrefix(sessionId: SessionId): ResultAsync<LoadedValidatedPrefixV2, SessionEventLogStoreError>;
     private appendImpl;
     private loadImpl;
     private readManifestOrEmpty;
+    private loadValidatedPrefixImpl;
     private loadTruthOrEmpty;
     private appendManifestRecords;
     private unwrap;