oc2token 0.1.0

package/dist/src/cache/schema.js

@@ -0,0 +1,308 @@
+import { createHash } from "node:crypto";
+import { DomainError } from "../domain/errors.js";
+import { parseTokenComponents, recorded_total, } from "../domain/index.js";
+import { CACHE_FORMAT, CURRENT_CACHE_SCHEMA_VERSION, RECORDS_FORMAT, } from "./types.js";
+const FORBIDDEN_KEY = /(?:prompt|tool.?input|tool.?output|api.?key|authorization|password|secret|session.?title|session.?name|raw.?content)/i;
+const SAFE_ID = /^[^\u0000-\u001f]{1,512}$/;
+const SAFE_REVISION = /^[a-zA-Z0-9._:-]{1,256}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(message, cause) {
+    throw new DomainError("cache-corrupt", message, { cause });
+}
+function stringField(value, name, pattern = SAFE_ID) {
+    if (typeof value !== "string" || !pattern.test(value)) {
+        fail(`${name} must be a bounded string`);
+    }
+    return value;
+}
+function dateField(value, name) {
+    const date = value instanceof Date ? value : new Date(String(value));
+    if (Number.isNaN(date.getTime())) {
+        fail(`${name} must be a valid date`);
+    }
+    return date.toISOString();
+}
+function recordField(value, name) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        fail(`${name} must be a non-negative safe integer`);
+    }
+    return value;
+}
+function recordFromUnknown(value, index) {
+    if (!isRecord(value)) {
+        fail(`records[${index}] must be an object`);
+    }
+    const components = parseTokenComponents(value);
+    const sessionID = stringField(value.sessionID, `records[${index}].sessionID`);
+    const messageID = stringField(value.messageID, `records[${index}].messageID`);
+    const key = stringField(value.key ?? `${sessionID}/${messageID}`, `records[${index}].key`);
+    const model = stringField(value.model ?? "unknown", `records[${index}].model`);
+    const tokenRevision = stringField(value.tokenRevision ?? revisionFor(components, value.completeness), `records[${index}].tokenRevision`, SAFE_REVISION);
+    const completeness = value.completeness ?? "final";
+    if (completeness !== "final" && completeness !== "provisional") {
+        fail(`records[${index}].completeness must be final or provisional`);
+    }
+    const rawProvider = value.provider ?? "opencode";
+    if (rawProvider !== "opencode" && rawProvider !== "codex" && rawProvider !== "antigravity") {
+        fail(`records[${index}].provider must be one of opencode, codex, antigravity`);
+    }
+    const provider = rawProvider;
+    // Project field: optional, may contain slashes (paths). Validate length and control chars separately.
+    let project;
+    if (value.project !== undefined && value.project !== null) {
+        if (typeof value.project !== "string") {
+            fail(`records[${index}].project must be a string when present`);
+        }
+        const trimmed = value.project.trim();
+        if (trimmed.length === 0) {
+            project = undefined;
+        }
+        else {
+            if (trimmed.length > 1024 || /[\u0000-\u001f]/.test(trimmed)) {
+                fail(`records[${index}].project must be 1..1024 chars without control characters`);
+            }
+            project = trimmed;
+        }
+    }
+    const normalized = {
+        key,
+        sessionID,
+        messageID,
+        createdAt: dateField(value.createdAt, `records[${index}].createdAt`),
+        model,
+        ...components,
+        recorded_total: recorded_total(components),
+        tokenRevision,
+        observedAt: dateField(value.observedAt ?? new Date(), `records[${index}].observedAt`),
+        completeness,
+        provider,
+        ...(project === undefined ? {} : { project }),
+    };
+    // A caller-provided total is metadata only. It is never trusted or written;
+    // the normalized sum is recomputed from the five validated components.
+    if ("recorded_total" in value && value.recorded_total !== normalized.recorded_total) {
+        fail(`records[${index}].recorded_total does not match its components`);
+    }
+    return normalized;
+}
+function revisionFor(components, completeness) {
+    return createHash("sha256")
+        .update(JSON.stringify({ ...components, completeness }))
+        .digest("hex");
+}
+/** Convert a domain record to a whitelist-only JSON record. */
+export function normalizeRecord(record) {
+    return recordFromUnknown(record, 0);
+}
+export function toDomainRecord(record) {
+    // The domain record intentionally contains Date values. The cast is limited
+    // to this boundary; all fields were validated by parseRecordsDocument first.
+    return {
+        ...record,
+        createdAt: new Date(record.createdAt),
+        observedAt: new Date(record.observedAt),
+    };
+}
+export function serializeRecords(records) {
+    const normalized = records.map(normalizeRecord);
+    const document = {
+        format: RECORDS_FORMAT,
+        schemaVersion: CURRENT_CACHE_SCHEMA_VERSION,
+        records: normalized,
+    };
+    return `${JSON.stringify(document)}\n`;
+}
+function schemaVersion(value) {
+    const version = value.schemaVersion ?? value.version ?? 0;
+    if (!Number.isSafeInteger(version) || version < 0) {
+        fail("schemaVersion must be a non-negative integer");
+    }
+    return version;
+}
+/** Migrate the small v0 record shape used by early development snapshots. */
+export function migrateRecordsDocument(value) {
+    if (!isRecord(value)) {
+        fail("records document must be an object");
+    }
+    const version = schemaVersion(value);
+    if (version > CURRENT_CACHE_SCHEMA_VERSION) {
+        throw new DomainError("cache-corrupt", "records document uses a future schema");
+    }
+    const rawRecords = value.records ?? value.items;
+    if (!Array.isArray(rawRecords)) {
+        fail("records document must contain a records array");
+    }
+    const records = rawRecords.map((record, index) => {
+        if (version === 0 && isRecord(record)) {
+            const legacyTokens = isRecord(record.tokens) ? record.tokens : {};
+            return {
+                ...record,
+                ...legacyTokens,
+                createdAt: record.createdAt ?? record.timestamp,
+                observedAt: record.observedAt ?? record.observed,
+                cacheRead: record.cacheRead ?? (isRecord(record.cache) ? record.cache.read : undefined),
+                cacheWrite: record.cacheWrite ?? (isRecord(record.cache) ? record.cache.write : undefined),
+            };
+        }
+        return record;
+    }).map(recordFromUnknown);
+    return {
+        migrated: version !== CURRENT_CACHE_SCHEMA_VERSION || value.format !== RECORDS_FORMAT,
+        value: { format: RECORDS_FORMAT, schemaVersion: CURRENT_CACHE_SCHEMA_VERSION, records },
+    };
+}
+function safeSnapshotValue(value, depth = 0) {
+    if (depth > 12) {
+        fail("snapshot metadata is too deeply nested");
+    }
+    if (value instanceof Date) {
+        return { $oc2Date: dateField(value, "snapshot date") };
+    }
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        if (typeof value === "string" && value.length > 8192) {
+            fail("snapshot metadata string is too large");
+        }
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value)) {
+            fail("snapshot metadata number must be a safe integer");
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (value.length > 4096) {
+            fail("snapshot metadata array is too large");
+        }
+        return value.map((entry) => safeSnapshotValue(entry, depth + 1));
+    }
+    if (isRecord(value)) {
+        const result = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === undefined) {
+                continue;
+            }
+            if (FORBIDDEN_KEY.test(key) || key === "content" || key === "parts" || key === "title") {
+                continue;
+            }
+            result[key] = safeSnapshotValue(entry, depth + 1);
+        }
+        return result;
+    }
+    fail("snapshot metadata contains an unsupported value");
+}
+export function sanitizeSnapshot(snapshot) {
+    return safeSnapshotValue(snapshot);
+}
+function decodeSnapshotValue(value) {
+    if (Array.isArray(value))
+        return value.map(decodeSnapshotValue);
+    if (!isRecord(value))
+        return value;
+    if (Object.keys(value).length === 1 && typeof value.$oc2Date === "string") {
+        return new Date(value.$oc2Date);
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, decodeSnapshotValue(entry)]));
+}
+export function deserializeSnapshot(value, records) {
+    const decoded = decodeSnapshotValue(value);
+    if (isRecord(decoded) && "records" in decoded) {
+        return { ...decoded, records };
+    }
+    return decoded;
+}
+export function serializeSnapshot(snapshot) {
+    return sanitizeSnapshot(snapshot);
+}
+export function sha256(contents) {
+    return createHash("sha256").update(contents, "utf8").digest("hex");
+}
+function safeRecordFile(value) {
+    if (typeof value !== "string" || !/^records-[a-zA-Z0-9._-]+\.json$/.test(value)) {
+        fail("manifest recordFile is not a safe records filename");
+    }
+    return value;
+}
+export function migrateManifestDocument(value) {
+    if (!isRecord(value)) {
+        fail("manifest must be an object");
+    }
+    const version = schemaVersion(value);
+    if (version > CURRENT_CACHE_SCHEMA_VERSION) {
+        throw new DomainError("cache-corrupt", "manifest uses a future schema");
+    }
+    const source = (version === 0 && isRecord(value.snapshotData) ? value.snapshotData : value.snapshot) ?? {};
+    const recordFile = value.recordFile ?? value.recordsFile;
+    const generation = value.generation ?? 0;
+    if (!Number.isSafeInteger(generation) || generation < 0) {
+        fail("manifest generation must be a non-negative integer");
+    }
+    const recordBytes = value.recordBytes ?? value.bytes;
+    if (!Number.isSafeInteger(recordBytes) || recordBytes < 0) {
+        fail("manifest recordBytes must be a non-negative integer");
+    }
+    const recordSha256 = stringField(value.recordSha256 ?? value.sha256, "manifest recordSha256", /^[a-f0-9]{64}$/i);
+    const createdAt = dateField(value.createdAt ?? value.created ?? new Date(0), "manifest createdAt");
+    const complete = value.complete ?? (version === 0 ? true : undefined);
+    if (complete !== true) {
+        fail("manifest is incomplete");
+    }
+    let providerFingerprints;
+    if (isRecord(value.providerFingerprints)) {
+        const fingerprints = {};
+        for (const [key, entry] of Object.entries(value.providerFingerprints)) {
+            if ((key === "opencode" || key === "codex" || key === "antigravity") &&
+                typeof entry === "string" &&
+                entry.length > 0 &&
+                entry.length <= 512 &&
+                /^[a-zA-Z0-9._:-]{1,256}$/.test(entry)) {
+                fingerprints[key] = entry;
+            }
+        }
+        if (Object.keys(fingerprints).length > 0) {
+            providerFingerprints = fingerprints;
+        }
+    }
+    const manifest = {
+        format: CACHE_FORMAT,
+        schemaVersion: CURRENT_CACHE_SCHEMA_VERSION,
+        manifestVersion: Number.isSafeInteger(value.manifestVersion) ? value.manifestVersion : 1,
+        complete: true,
+        generation: generation,
+        createdAt,
+        recordFile: safeRecordFile(recordFile),
+        recordBytes: recordBytes,
+        recordSha256,
+        snapshot: sanitizeSnapshot(source),
+        ...(providerFingerprints ? { providerFingerprints } : {}),
+    };
+    return {
+        value: manifest,
+        migrated: version !== CURRENT_CACHE_SCHEMA_VERSION ||
+            value.format !== CACHE_FORMAT ||
+            (value.providerFingerprints !== undefined && providerFingerprints === undefined),
+    };
+}
+export function parseRecords(contents) {
+    try {
+        return migrateRecordsDocument(JSON.parse(contents));
+    }
+    catch (error) {
+        if (error instanceof DomainError)
+            throw error;
+        fail("records JSON is invalid", error);
+    }
+}
+export function parseManifest(contents) {
+    try {
+        return migrateManifestDocument(JSON.parse(contents));
+    }
+    catch (error) {
+        if (error instanceof DomainError)
+            throw error;
+        fail("manifest JSON is invalid", error);
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/src/cache/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/cache/schema.ts"],"names":[],"mappings":"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"}

package/dist/src/cache/store.d.ts

@@ -0,0 +1,46 @@
+import type { SnapshotStore, SnapshotStoreCommitOptions, SnapshotStoreReadOptions } from "../domain/index.js";
+import { type CacheCommitResult, type CacheReadResult, type CacheStoreOptions, type OrphanRecoveryResult, type StoredSnapshot, type UsageRecord } from "./types.js";
+export declare class NormalizedCacheStore implements SnapshotStore {
+    readonly directory: string;
+    readonly manifestPath: string;
+    private readonly fs;
+    private readonly clock;
+    private readonly process;
+    private readonly random;
+    private readonly lock;
+    private readonly recoverOrphans;
+    private static sequence;
+    private static readonly commitChains;
+    constructor(directory: string, dependencies?: CacheStoreOptions);
+    constructor(options: CacheStoreOptions);
+    private ensureDirectory;
+    private nextName;
+    private syncDirectory;
+    private writeUniqueAndRename;
+    private currentManifestVersion;
+    /** Remove only OC2Token's own temporary files, never arbitrary cache files. */
+    recoverOrphanTemps(): Promise<OrphanRecoveryResult>;
+    private recoverOrphanTempsInternal;
+    private isTemp;
+    readDetailed(): Promise<CacheReadResult>;
+    read(options?: SnapshotStoreReadOptions): Promise<StoredSnapshot | null>;
+    private commitNormalized;
+    /**
+     * Commit is non-blocking across processes: a held lock returns cache_busy and
+     * leaves the caller's correct in-memory snapshot untouched. Calls in this
+     * process are serialized for the complete record+manifest publication.
+     */
+    commitDetailed(snapshot: StoredSnapshot, records?: readonly UsageRecord[]): Promise<CacheCommitResult>;
+    commit(snapshot: StoredSnapshot, options?: SnapshotStoreCommitOptions): Promise<void>;
+}
+export declare const FileCacheStore: typeof NormalizedCacheStore;
+export declare const SnapshotCacheStore: typeof NormalizedCacheStore;
+/** Domain-facing facade: detailed callers can inspect cache_busy via commitDetailed. */
+export declare class SnapshotStoreAdapter implements SnapshotStore {
+    readonly detailed: NormalizedCacheStore;
+    constructor(detailed: NormalizedCacheStore);
+    read(_options?: SnapshotStoreReadOptions): Promise<StoredSnapshot | null>;
+    commit(snapshot: StoredSnapshot, options?: SnapshotStoreCommitOptions): Promise<void>;
+}
+export declare function createSnapshotStore(options: CacheStoreOptions): SnapshotStoreAdapter;
+export declare function createNormalizedCacheStore(options: CacheStoreOptions): NormalizedCacheStore;