@vibefield/rosetta-protocol 0.0.0-stage → 0.1.0

package/dist/grants.js

@@ -0,0 +1,160 @@
+// Per-session expiring grants (docs/AUTH.md): the TypeScript twin of
+// `crates/server/src/grant.rs`, for the supervisor that mints them (fieldd)
+// and for its tests. Node-only — it signs with `node:crypto` — so it is its
+// own package entry, `@vibefield/rosetta-protocol/grants`, never part of the browser
+// client. A browser carries a grant as an opaque string (the client's
+// `credential` option); only the key's holder mints or verifies one.
+//
+// A grant is `<base64url(payload)>.<base64url(HMAC-SHA256(key, payload))>`,
+// unpadded. `payload` is the RFC 8785 canonical JSON of the claims below.
+// Both sides read `crates/server/tests/fixtures/grants.json`.
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { base64UrlDecode, base64UrlEncode } from "./base64url.js";
+/** The only payload version a daemon accepts. */
+export const GRANT_VERSION = 1;
+/** The scope every grant-openable route needs. */
+export const SCOPE_READ = "read";
+/**
+ * The recorded-file read (`/read/{target_index}`), which reads a file from the
+ * daemon's disk by the transcript's reference — more than the transcript, so it
+ * is minted separately: the file route needs it beside {@link SCOPE_READ}, and
+ * the minter decides which principals hold it (docs/AUTH.md §5.4).
+ */
+export const SCOPE_FILES = "files";
+/** A daemon refuses to start with a shorter key. */
+export const MIN_GRANT_KEY_BYTES = 32;
+/** The largest encoded grant a daemon reads. */
+export const MAX_GRANT_BYTES = 4096;
+const MAC_BYTES = 32;
+/** A lone UTF-16 surrogate: not Unicode text, so not I-JSON (RFC 8785 §3.1). */
+const LONE_SURROGATE = /\p{Cs}/u;
+function isArray(value) {
+    return Array.isArray(value);
+}
+/**
+ * RFC 8785 (JCS): members sorted by UTF-16 code units (JavaScript's default
+ * sort), no whitespace, strings and numbers exactly as `JSON.stringify`
+ * writes them. Throws on what I-JSON forbids: non-finite numbers and lone
+ * surrogates.
+ */
+export function canonicalize(value) {
+    if (typeof value === "string") {
+        if (LONE_SURROGATE.test(value))
+            throw new TypeError("canonical JSON strings are Unicode text");
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("canonical JSON numbers are finite");
+        return JSON.stringify(value);
+    }
+    if (value === null || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (isArray(value))
+        return `[${value.map(canonicalize).join(",")}]`;
+    const members = Object.keys(value)
+        .sort()
+        .flatMap((key) => {
+        const member = value[key];
+        return member === undefined ? [] : [`${canonicalize(key)}:${canonicalize(member)}`];
+    });
+    return `{${members.join(",")}}`;
+}
+/** The canonical payload text of `claims` (exactly the five members). */
+export function canonicalPayload(claims) {
+    return canonicalize({
+        cid: claims.cid,
+        exp: claims.exp,
+        scope: [...claims.scope],
+        sid: claims.sid,
+        v: claims.v,
+    });
+}
+function isClaims(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const claims = value;
+    return (claims.v === GRANT_VERSION &&
+        typeof claims.sid === "string" &&
+        claims.sid !== "" &&
+        typeof claims.cid === "string" &&
+        claims.cid !== "" &&
+        typeof claims.exp === "number" &&
+        Number.isSafeInteger(claims.exp) &&
+        claims.exp >= 0 &&
+        Array.isArray(claims.scope) &&
+        claims.scope.every((entry) => typeof entry === "string"));
+}
+/** Canonical version-1 claims from payload bytes, or `null`. */
+function claimsFrom(payload) {
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(payload);
+        const value = JSON.parse(text);
+        // One spelling per grant: the payload must be its own canonical form.
+        return isClaims(value) && canonicalPayload(value) === text ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sign(key, payload) {
+    return createHmac("sha256", key).update(payload).digest();
+}
+/** Mint a grant. Throws on claims a daemon would call malformed, or a short key. */
+export function mintGrant(key, claims) {
+    if (key.length < MIN_GRANT_KEY_BYTES) {
+        throw new RangeError(`a grant key is at least ${MIN_GRANT_KEY_BYTES} bytes`);
+    }
+    if (!isClaims(claims))
+        throw new TypeError("not version-1 grant claims");
+    const payload = new TextEncoder().encode(canonicalPayload(claims));
+    return `${base64UrlEncode(payload)}.${base64UrlEncode(sign(key, payload))}`;
+}
+/**
+ * Verify as the daemon does: the MAC first (constant-time), then the
+ * canonical form, version, ids and expiry range, then `exp > nowMs`.
+ */
+export function verifyGrant(key, grant, nowMs) {
+    const refused = (reason) => ({ ok: false, reason });
+    if (grant.length > MAX_GRANT_BYTES)
+        return refused("malformed");
+    const dot = grant.indexOf(".");
+    if (dot < 0)
+        return refused("malformed");
+    const payload = base64UrlDecode(grant.slice(0, dot));
+    const mac = base64UrlDecode(grant.slice(dot + 1));
+    if (payload === null || mac === null || mac.length !== MAC_BYTES)
+        return refused("malformed");
+    if (!timingSafeEqual(sign(key, payload), mac))
+        return refused("bad-signature");
+    const claims = claimsFrom(payload);
+    if (claims === null)
+        return refused("malformed");
+    if (claims.exp <= nowMs)
+        return refused("expired");
+    return { ok: true, claims };
+}
+/** The `Authorization` value that presents `grant`. */
+export function grantAuthorization(grant) {
+    return `Rosetta-Grant ${grant}`;
+}
+/**
+ * Read a grant — an `Authorization: Rosetta-Grant <grant>` value or the bare
+ * grant — WITHOUT verifying it, e.g. to learn when a held grant expires.
+ * `null` unless it carries canonical version-1 claims. Only a key holder
+ * can tell whether it is authentic.
+ */
+export function parseGrantHeader(value) {
+    const text = value.trim();
+    const scheme = /^rosetta-grant\s+/i.exec(text);
+    const grant = scheme === null ? text : text.slice(scheme[0].length);
+    const dot = grant.indexOf(".");
+    if (dot < 0 || grant.length > MAX_GRANT_BYTES)
+        return null;
+    const payload = base64UrlDecode(grant.slice(0, dot));
+    const mac = base64UrlDecode(grant.slice(dot + 1));
+    if (payload === null || mac === null || mac.length !== MAC_BYTES)
+        return null;
+    const claims = claimsFrom(payload);
+    return claims === null ? null : { grant, claims };
+}

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+export type * from "./generated/ApiError.js";
+export type * from "./generated/AssetRef.js";
+export type * from "./generated/CanonicalText.js";
+export type * from "./generated/CommandResponse.js";
+export type * from "./generated/AttachmentKind.js";
+export type * from "./generated/AttachmentRef.js";
+export type * from "./generated/AttachmentSource.js";
+export type * from "./generated/AttachmentUnavailableReason.js";
+export type * from "./generated/BackfillState.js";
+export type * from "./generated/BoostRequest.js";
+export type * from "./generated/BoostResponse.js";
+export type * from "./generated/ContributionResponse.js";
+export type * from "./generated/ContributionRow.js";
+export type * from "./generated/CitationRef.js";
+export type * from "./generated/CollaborationChannel.js";
+export type * from "./generated/CollaborationEvent.js";
+export type * from "./generated/CollaborationEventKind.js";
+export type * from "./generated/CollaborationStatus.js";
+export type * from "./generated/CollaborationTimeline.js";
+export type * from "./generated/DaemonStatus.js";
+export type * from "./generated/DiscoveriesResponse.js";
+export type * from "./generated/DiscoveryRow.js";
+export type * from "./generated/EnableRequest.js";
+export type * from "./generated/EnableResponse.js";
+export type * from "./generated/ErrorCode.js";
+export type * from "./generated/HeatmapDay.js";
+export type * from "./generated/HeatmapResponse.js";
+export type * from "./generated/HourTotal.js";
+export type * from "./generated/HubStatus.js";
+export type * from "./generated/IngestPhase.js";
+export type * from "./generated/IngestProgress.js";
+export type * from "./generated/GroupDerivation.js";
+export type * from "./generated/GroupKind.js";
+export type * from "./generated/ModelDay.js";
+export type * from "./generated/Mutation.js";
+export type * from "./generated/Notice.js";
+export type * from "./generated/ParticipantColor.js";
+export type * from "./generated/ProjectBackfill.js";
+export type * from "./generated/ProjectRow.js";
+export type * from "./generated/ProjectsResponse.js";
+export type * from "./generated/RuntimeBackfill.js";
+export type * from "./generated/RuntimeIngestStatus.js";
+export type * from "./generated/RuntimeProvenance.js";
+export type * from "./generated/RuntimeRow.js";
+export type * from "./generated/ResponseGroup.js";
+export type * from "./generated/ResponseRuntime.js";
+export type * from "./generated/ResourceRef.js";
+export type * from "./generated/RuntimesResponse.js";
+export type * from "./generated/SearchHit.js";
+export type * from "./generated/SearchReadiness.js";
+export type * from "./generated/SearchRequest.js";
+export type * from "./generated/SearchResponse.js";
+export type * from "./generated/SearchState.js";
+export type * from "./generated/SearchBuildProgress.js";
+export type * from "./generated/SearchBuildStage.js";
+export type * from "./generated/ServerFrame.js";
+export type * from "./generated/SessionResponse.js";
+export type * from "./generated/SessionRole.js";
+export type * from "./generated/SessionRow.js";
+export type * from "./generated/SessionActivity.js";
+export type * from "./generated/SessionDelegation.js";
+export type * from "./generated/SessionsResponse.js";
+export type * from "./generated/Stamp.js";
+export type * from "./generated/StatusResponse.js";
+export type * from "./generated/StreamState.js";
+export type * from "./generated/SummaryPurpose.js";
+export type * from "./generated/TimelineBody.js";
+export type * from "./generated/TimelineEntry.js";
+export type * from "./generated/TimelineEntryResponse.js";
+export type * from "./generated/TimelineMeta.js";
+export type * from "./generated/TimelineMetaArtifact.js";
+export type * from "./generated/TimelineMetaArtifactSource.js";
+export type * from "./generated/TimelineMetaPlan.js";
+export type * from "./generated/TimelineMetaPlanSource.js";
+export type * from "./generated/TimelineMetaTask.js";
+export type * from "./generated/TimelineMetaWorkflow.js";
+export type * from "./generated/TimelineGroup.js";
+export type * from "./generated/TimelinePage.js";
+export type * from "./generated/TokenSnapshot.js";
+export type * from "./generated/TaskSnapshot.js";
+export type * from "./generated/TaskSnapshotItem.js";
+export type * from "./generated/ToolAction.js";
+export type * from "./generated/ToolInteraction.js";
+export type * from "./generated/StatusBasis.js";
+export type * from "./generated/ToolStatus.js";
+export type * from "./generated/UsageCost.js";
+export type * from "./generated/UsageResponse.js";
+export type * from "./generated/DayUsageResponse.js";
+export type * from "./generated/ModelHour.js";
+export type * from "./generated/ActivityResponse.js";
+export type * from "./generated/ActivitySession.js";
+export type * from "./generated/TurnSpan.js";
+export type * from "./generated/TurnGap.js";
+export type * from "./generated/UsageScope.js";
+export type * from "./generated/PricingResponse.js";
+export type * from "./generated/PricingSource.js";
+export type * from "./generated/ServiceTier.js";
+export type * from "./generated/WorkflowJournalKind.js";
+export type * from "./generated/WorkflowJournalObservation.js";
+export type * from "./generated/WorkflowAttempt.js";
+export type * from "./generated/WorkflowPhase.js";
+export type * from "./generated/WorkflowResultKind.js";
+export type * from "./generated/WorkflowRun.js";
+export type * from "./generated/WorkflowRunStatus.js";
+export type * from "./generated/WorkflowUsage.js";
+export type * from "./generated/WorkflowWorker.js";
+export type * from "./generated/WorkflowWorkerState.js";
+export type * from "./generated/serde_json/JsonValue.js";
+export * from "./client.js";
+export type { ImageVariant } from "./generated/ImageVariant.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./client.js";

package/dist/ordered-cache.d.ts

@@ -0,0 +1,15 @@
+/** Mutable internal ordering with immutable published arrays. Updates whose
+ * sort key is unchanged replace one slot; moved/new rows use binary insertion. */
+export declare class OrderedCache<T> {
+    private readonly byId;
+    private ordered;
+    private published;
+    private readonly id;
+    private readonly compare;
+    constructor(id: (row: T) => string, compare: (a: T, b: T) => number);
+    get(id: string): T | undefined;
+    private position;
+    set(row: T): void;
+    replace(rows: readonly T[]): void;
+    values(): T[];
+}

package/dist/ordered-cache.js

@@ -0,0 +1,63 @@
+/** Mutable internal ordering with immutable published arrays. Updates whose
+ * sort key is unchanged replace one slot; moved/new rows use binary insertion. */
+export class OrderedCache {
+    byId = new Map();
+    ordered = [];
+    published = null;
+    id;
+    compare;
+    constructor(id, compare) {
+        this.id = id;
+        this.compare = compare;
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    position(row) {
+        let low = 0;
+        let high = this.ordered.length;
+        while (low < high) {
+            const mid = (low + high) >>> 1;
+            const candidate = this.ordered[mid];
+            if (candidate === undefined) {
+                // `mid` is always within `[0, ordered.length)` while `low < high`, so a hole
+                // here means the ordering is already corrupt. Fail loudly rather than break
+                // out and return a position that would splice the row into the wrong slot.
+                throw new Error(`OrderedCache invariant violated: no row at index ${mid} of ${this.ordered.length}`);
+            }
+            if (this.compare(candidate, row) < 0)
+                low = mid + 1;
+            else
+                high = mid;
+        }
+        return low;
+    }
+    set(row) {
+        const id = this.id(row);
+        const old = this.byId.get(id);
+        if (old === row)
+            return;
+        this.published = null;
+        if (old !== undefined) {
+            const at = this.position(old);
+            if (this.compare(old, row) === 0) {
+                this.ordered[at] = row;
+                this.byId.set(id, row);
+                return;
+            }
+            this.ordered.splice(at, 1);
+        }
+        this.ordered.splice(this.position(row), 0, row);
+        this.byId.set(id, row);
+    }
+    replace(rows) {
+        this.byId.clear();
+        for (const row of rows)
+            this.byId.set(this.id(row), row);
+        this.ordered = [...this.byId.values()].sort(this.compare);
+        this.published = null;
+    }
+    values() {
+        return (this.published ??= this.ordered.slice());
+    }
+}

package/dist/protocol-version.d.mts

@@ -0,0 +1 @@
+export const PROTOCOL_VERSION: number;

package/dist/protocol-version.mjs

@@ -0,0 +1,2 @@
+// Shared wire version; checked against Rust in the wire tests.
+export const PROTOCOL_VERSION = 27;

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@vibefield/rosetta-protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./protocol-version": {
+      "types": "./dist/protocol-version.d.mts",
+      "import": "./dist/protocol-version.mjs"
+    },
+    "./grants": {
+      "types": "./dist/grants.d.ts",
+      "import": "./dist/grants.js"
+    }
+  },
+  "scripts": {
+    "build": "node ../../tools/npm/build.mjs",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json",
+    "pretest": "npm run build",
+    "test": "node --test test/*.test.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vibefield/rosetta.git",
+    "directory": "clients/ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "Rosetta protocol types, transport client, subscriptions, and session grants.",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.18"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}