sessionpipe-core 0.1.1 → 0.3.0

package/dist/src/control/verify.d.ts

@@ -0,0 +1,171 @@
+/** One passkey tap vouches for a day key for at most this long. */
+export declare const GRANT_MAX_MS: number;
+/** Clock slack between the signing device, the receiver and the machine. */
+export declare const SKEW_MS: number;
+/** The machine judges a command by when it was SIGNED: a message sent while the lid
+ *  was shut still runs when the machine wakes, up to a day later. */
+export declare const MACHINE_MAX_AGE_MS: number;
+/** A receiver's early check is stricter: a command is carried within ten minutes of
+ *  being signed, or not at all. */
+export declare const RECEIVER_MAX_AGE_MS: number;
+/** How long a machine remembers a nonce: longer than MACHINE_MAX_AGE_MS + SKEW_MS. */
+export declare const NONCE_TTL_MS: number;
+/** The whole command string, in UTF-16 code units (what JSON.parse sees). */
+export declare const CMD_MAX = 12000;
+/** A prompt's text, in characters. */
+export declare const TEXT_MAX = 4000;
+/** A permission answer's note. */
+export declare const NOTE_MAX = 2000;
+/** A grant string. */
+export declare const GRANT_STR_MAX = 2000;
+export declare const COMMAND_TYPE = "sessionpipe.control";
+export declare const GRANT_TYPE = "sessionpipe.grant";
+export declare const CONTROL_KINDS: readonly ["prompt", "permission.answer", "cancel", "start"];
+export type ControlKind = (typeof CONTROL_KINDS)[number];
+/** COSE algorithm ids a trusted key may use. */
+export declare const ES256 = -7;
+export declare const RS256 = -257;
+/** A key enrolled on the machine: a passkey's credential id, COSE alg and SPKI (base64url). */
+export interface TrustedKey {
+    id: string;
+    alg: number;
+    spki: string;
+}
+/** A WebAuthn assertion: credential id, authenticatorData, clientDataJSON, signature (base64url). */
+export interface Assertion {
+    cred: string;
+    ad: string;
+    cd: string;
+    sig: string;
+}
+/** The day's grant: a passkey's assertion over sha256(str), where str names the day key. */
+export interface GrantBundle extends Assertion {
+    str: string;
+}
+/** What a receiver carries for one command (control.json minus the receiver's envelope). */
+export interface SignedCommand {
+    cmd: string;
+    csig?: string | null;
+    grant?: GrantBundle | null;
+    confirm?: Assertion | null;
+}
+export interface Grant {
+    v: 1;
+    t: typeof GRANT_TYPE;
+    pub: string;
+    iat: number;
+    exp: number;
+    rp: string;
+}
+export interface ControlCommand {
+    v: 1;
+    t: typeof COMMAND_TYPE;
+    machine: string;
+    kind: ControlKind;
+    /** `<harness>:<id>`, e.g. `claude-code:8c132906-…`. */
+    session: string;
+    text?: string;
+    for?: string;
+    decision?: "allow" | "deny";
+    note?: string;
+    cwd?: string;
+    nonce: string;
+    iat: number;
+}
+/** Why a command was refused. Stable: conformance vectors and acks name these. */
+export type RefusalCode = "malformed" | "not_a_command" | "wrong_machine" | "unknown_kind" | "bad_session" | "bad_fields" | "bad_nonce" | "too_old" | "future" | "unsigned" | "untrusted_key" | "bad_assertion" | "bad_grant" | "outside_grant" | "bad_csig" | "replay" | "nonce_store";
+export type Verdict = {
+    ok: true;
+    cmd: ControlCommand;
+    via: "grant" | "confirm";
+    key: string;
+} | {
+    ok: false;
+    code: RefusalCode;
+    why: string;
+};
+export interface VerifyOptions {
+    /** This machine's id; a command for another machine is refused. */
+    machine: string;
+    /** The receiver's WebAuthn rp id the keys were enrolled for (well-known control.signing.rp_id). */
+    rpId: string;
+    /** The keys enrolled on this machine (or, for a receiver's early check, the account's). */
+    trusted: TrustedKey[];
+    /** Epoch ms. */
+    now: number;
+    /** MACHINE_MAX_AGE_MS on a machine (default), RECEIVER_MAX_AGE_MS on a receiver. */
+    maxAgeMs?: number;
+    /** Called once, last, only for a command whose signatures all verified: answer
+     *  true when the nonce was seen before, otherwise record it (durably) and answer
+     *  false. A throw refuses the command (`nonce_store`): never run what could not
+     *  be remembered. Omit it on a receiver's early check. */
+    seenNonce?: (nonce: string) => boolean | Promise<boolean>;
+}
+export declare function b64url(bytes: Uint8Array | ArrayBuffer): string;
+/** base64url without padding, strictly; null for anything else. */
+export declare function fromB64url(s: unknown): Uint8Array | null;
+export declare function sha256(data: string | Uint8Array): Promise<Uint8Array>;
+/** A DER ECDSA signature (what WebAuthn returns) as the 64-byte r‖s WebCrypto verifies.
+ *  Strict: every length must match the bytes, so one signature has one encoding (a
+ *  P-256 signature is at most 72 bytes, so the short length form is the only one). */
+export declare function derToRaw(der: Uint8Array): Uint8Array | null;
+/** Can this key be enrolled at all? A machine refuses to trust a key it could never verify with. */
+export declare function keyUsable(key: TrustedKey): Promise<boolean>;
+/** A WebAuthn origin a key may have been used from: https on the rp id or a subdomain;
+ *  for rp id `localhost`, plain http on any port too. A bare origin, as a browser writes it. */
+export declare function originAllowed(origin: unknown, rpId: string): boolean;
+type Check = {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
+/** One passkey assertion over `challenge`, made with `key`, by a verified person. */
+export declare function verifyAssertion(challenge: Uint8Array, a: Assertion | null | undefined, key: TrustedKey, rpId: string): Promise<Check>;
+/** What a passkey signs to enroll on a machine: bound to that machine and that pairing code. */
+export declare function pairChallenge(machine: string, code: string): Promise<Uint8Array>;
+/** The enrollment proof: the new key's assertion over pairChallenge(machine, code).
+ *  Only after this verifies does the key go into the machine's trust store. */
+export declare function verifyEnrollment(o: {
+    machine: string;
+    code: string;
+    key: TrustedKey;
+    proof: Assertion;
+    rpId: string;
+}): Promise<Check>;
+type Parsed = {
+    ok: true;
+    cmd: ControlCommand;
+} | {
+    ok: false;
+    code: RefusalCode;
+    why: string;
+};
+/** The session id rule per harness (ADAPTERS.md): Claude Code ids are UUIDs. */
+export declare function sessionIdOk(harness: string, id: string): boolean;
+/** Split `<harness>:<id>`; null when either half breaks its rule. */
+export declare function parseSessionRef(ref: unknown): {
+    harness: string;
+    id: string;
+} | null;
+/** Read the command's fields from the exact string. Structure only; no clock, no keys. */
+export declare function parseCommand(str: unknown): Parsed;
+/** The grant's fields, read from its exact string. */
+export declare function parseGrant(str: unknown, rpId: string): {
+    ok: true;
+    grant: Grant;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * Is this a command this machine may run? The checks, in the spec's order
+ * (CONTROL.md §5): the exact bytes parse; the command is for this machine; it is
+ * signed — a grant from a trusted key plus the day key's signature, or a confirm
+ * over sha256(cmd); it was signed within the age window; its nonce is new.
+ * The folder and open-attention checks that follow are the daemon's (they read
+ * the machine, not the command).
+ */
+export declare function verifyCommand(s: SignedCommand | null | undefined, o: VerifyOptions): Promise<Verdict>;
+export {};
+//# sourceMappingURL=verify.d.ts.map

package/dist/src/control/verify.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sessionpipe-core",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "sessionpipe core: protocol types, harness adapters, privacy filter and redaction rulesets, outbox and sinks. Zero runtime dependencies. (published unscoped until the @sessionpipe npm org exists; the code is the same)",
   "license": "Apache-2.0",
   "type": "module",
@@ -39,6 +39,10 @@
     "./schema": {
       "types": "./dist/schema/v1.d.ts",
       "import": "./dist/schema.js"
+    },
+    "./control": {
+      "types": "./dist/src/control/index.d.ts",
+      "import": "./dist/control.js"
     }
   },
   "types": "./dist/src/index.d.ts",