@aithos/sdk 0.1.0-alpha.6 → 0.1.0-alpha.60

package/dist/test/envelope.test.js

@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Unit tests for the signed-envelope primitive — both the SDK-internal
+// helper `signOwnerEnvelope` and the public surface
+// `AithosAuth.signEnvelope`.
+//
+// Two levels of testing:
+//
+//   1. Internal helper: tests that can inject deterministic `now` and
+//      `nonce` to lock byte-for-byte output. These guard against any
+//      future drift in canonicalization, default TTL, field order, or
+//      crypto wiring.
+//
+//   2. Public surface: tests that exercise the full path through
+//      `AithosAuth.signEnvelope`, including sphere resolution, throw
+//      semantics, and binding to the loaded owner's DID. These guard
+//      the developer contract documented in the JSDoc.
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { createBrowserIdentity, sign as ed25519Sign, verify as ed25519Verify, } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDKError, memoryKeyStore, noopStore, } from "../src/index.js";
+import { signOwnerEnvelope } from "../src/internal/envelope.js";
+import { serializeRecoveryFile } from "../src/internal/recovery-file.js";
+/* -------------------------------------------------------------------------- */
+/*  Test helpers                                                              */
+/* -------------------------------------------------------------------------- */
+/** Build a minimal AithosAuth, no network, no persistence. */
+function makeAuth() {
+    return new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        fetch: (() => {
+            throw new Error("network not expected in this test");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+}
+/** Recovery-file text + DID for a fresh BrowserIdentity. */
+function recoveryTextFor(handle, displayName) {
+    const id = createBrowserIdentity(handle, displayName);
+    return { text: serializeRecoveryFile(id).text, did: id.did };
+}
+/** Inline signer wrapping a raw seed — matches what data.ts does. */
+function inlineSigner(seed) {
+    return {
+        async sign(message) {
+            return ed25519Sign(message, seed);
+        },
+    };
+}
+/** base64url decoder for envelope.proof.proofValue. */
+function base64urlDecode(s) {
+    const std = s.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = std + "=".repeat((4 - (std.length % 4)) % 4);
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** Canonicalize a JS value the same way envelope.ts does — for the
+ *  test that recomputes the bytes the server would verify against. */
+function canonical(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return value.toString();
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map(canonical).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return ("{" +
+            keys.map((k) => JSON.stringify(k) + ":" + canonical(obj[k])).join(",") +
+            "}");
+    }
+    throw new Error(`Cannot canonicalize ${typeof value}`);
+}
+/* -------------------------------------------------------------------------- */
+/*  signOwnerEnvelope — internal helper                                       */
+/* -------------------------------------------------------------------------- */
+describe("signOwnerEnvelope (internal helper)", () => {
+    it("signs an envelope whose signature verifies under the signer's pubkey", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const envelope = await signOwnerEnvelope({
+            iss: id.did,
+            aud: "https://api.example.com/v1/widgets",
+            method: "myapp.widgets.create",
+            params: { name: "Widget #1" },
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+        });
+        // Re-derive the exact bytes the server would canonicalize and check.
+        const { proof, ...unsignedWithEmptyProof } = envelope;
+        const unsigned = {
+            ...unsignedWithEmptyProof,
+            proof: { ...proof, proofValue: "" },
+        };
+        const bytes = new TextEncoder().encode(canonical(unsigned));
+        const sig = base64urlDecode(envelope.proof.proofValue);
+        assert.ok(ed25519Verify(sig, bytes, id.public.publicKey), "envelope signature must verify under the public-sphere pubkey");
+    });
+    it("produces an envelope conforming to spec §11.2 shape", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const envelope = await signOwnerEnvelope({
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+        });
+        assert.equal(envelope["aithos-envelope"], "0.1.0");
+        assert.equal(envelope.iss, id.did);
+        assert.equal(envelope.aud, "https://api.example.com/v1/x");
+        assert.equal(envelope.method, "x.do");
+        assert.equal(typeof envelope.iat, "number");
+        assert.equal(typeof envelope.exp, "number");
+        assert.equal(typeof envelope.nonce, "string");
+        assert.ok(envelope.params_hash.startsWith("sha256-"));
+        assert.equal(envelope.proof.type, "Ed25519Signature2020");
+        assert.equal(envelope.proof.verificationMethod, `${id.did}#public`);
+        assert.equal(typeof envelope.proof.created, "string");
+        assert.ok(envelope.proof.proofValue.length > 0);
+    });
+    it("params_hash is canonical — key order does not affect the hash", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const common = {
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+            now: new Date("2024-01-01T00:00:00.000Z"),
+            nonce: "01HXJZK7MK8VPN0FQR5T6Y2A3Z",
+        };
+        const env1 = await signOwnerEnvelope({
+            ...common,
+            params: { alpha: 1, beta: 2, gamma: [3, 4] },
+        });
+        const env2 = await signOwnerEnvelope({
+            ...common,
+            params: { gamma: [3, 4], alpha: 1, beta: 2 },
+        });
+        assert.equal(env1.params_hash, env2.params_hash, "params_hash must be stable across JS object key order");
+    });
+    it("respects an explicit ttlSeconds", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const envelope = await signOwnerEnvelope({
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+            now: new Date("2024-01-01T00:00:00.000Z"),
+            ttlSeconds: 173,
+        });
+        assert.equal(envelope.exp - envelope.iat, 173);
+    });
+    it("defaults ttlSeconds to 60 — guards against drift from data.ts's prior behavior", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const envelope = await signOwnerEnvelope({
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+            now: new Date("2024-01-01T00:00:00.000Z"),
+        });
+        assert.equal(envelope.exp - envelope.iat, 60);
+    });
+    it("nonce defaults to a fresh value per call (unique across calls)", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const args = {
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+        };
+        const e1 = await signOwnerEnvelope(args);
+        const e2 = await signOwnerEnvelope(args);
+        assert.notEqual(e1.nonce, e2.nonce, "two successive calls must produce different nonces");
+    });
+    it("is deterministic when now and nonce are both injected (regression lock)", async () => {
+        // With identical inputs INCLUDING the override hooks, two calls must
+        // produce byte-for-byte identical envelopes — including the
+        // signature. This catches any future regression in canonicalization,
+        // ordering, default values, or signing path.
+        const id = createBrowserIdentity("alice", "Alice");
+        const args = {
+            iss: id.did,
+            aud: "https://api.example.com/v1/widgets",
+            method: "myapp.widgets.create",
+            params: { name: "Widget #1", count: 3, tags: ["a", "b"] },
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+            now: new Date("2024-01-01T00:00:00.000Z"),
+            nonce: "01HXJZK7MK8VPN0FQR5T6Y2A3Z",
+            ttlSeconds: 120,
+        };
+        const e1 = await signOwnerEnvelope(args);
+        const e2 = await signOwnerEnvelope(args);
+        assert.deepEqual(e1, e2, "envelope must be deterministic under fixed inputs");
+        // Belt and braces: also lock the timestamp arithmetic.
+        assert.equal(e1.iat, 1704067200);
+        assert.equal(e1.exp, 1704067320);
+        assert.equal(e1.nonce, "01HXJZK7MK8VPN0FQR5T6Y2A3Z");
+        assert.equal(e1.proof.created, "2024-01-01T00:00:00.000Z");
+        assert.equal(e1.proof.verificationMethod, `${id.did}#public`);
+    });
+});
+/* -------------------------------------------------------------------------- */
+/*  AithosAuth.signEnvelope — public surface                                  */
+/* -------------------------------------------------------------------------- */
+describe("AithosAuth.signEnvelope (public surface)", () => {
+    it("defaults to the public sphere when no sphere is passed", async () => {
+        const auth = makeAuth();
+        const { text, did } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        const envelope = await auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: { ok: true },
+        });
+        assert.equal(envelope.iss, did);
+        assert.equal(envelope.proof.verificationMethod, `${did}#public`);
+    });
+    it("honors explicit sphere overrides (root / public / circle / self)", async () => {
+        const auth = makeAuth();
+        const { text, did } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        for (const sphere of ["root", "public", "circle", "self"]) {
+            const envelope = await auth.signEnvelope({
+                aud: "https://api.example.com/v1/x",
+                method: "x.do",
+                params: {},
+                sphere,
+            });
+            assert.equal(envelope.proof.verificationMethod, `${did}#${sphere}`, `verificationMethod must end with #${sphere}`);
+        }
+    });
+    it("throws auth_not_signed_in when no owner is loaded", async () => {
+        const auth = makeAuth();
+        await assert.rejects(() => auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "auth_not_signed_in");
+    });
+    it("throws auth_invalid_sphere when an unknown sphere is passed (untyped caller)", async () => {
+        const auth = makeAuth();
+        const { text } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        await assert.rejects(() => auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            // Untyped callers (e.g. plain JS) could pass anything.
+            sphere: "bogus",
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "auth_invalid_sphere");
+    });
+    it("envelope ttlSeconds defaults to 60 — non-regression of internal default", async () => {
+        const auth = makeAuth();
+        const { text } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        const envelope = await auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+        });
+        assert.equal(envelope.exp - envelope.iat, 60);
+    });
+    it("envelope ttlSeconds is honored when provided", async () => {
+        const auth = makeAuth();
+        const { text } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        const envelope = await auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            ttlSeconds: 240,
+        });
+        assert.equal(envelope.exp - envelope.iat, 240);
+    });
+    it("envelope signs with the correct sphere key (sig verifies under that pubkey)", async () => {
+        const auth = makeAuth();
+        const id = createBrowserIdentity("alice", "Alice");
+        const { text } = serializeRecoveryFile(id);
+        await auth.signInWithRecovery({ file: text });
+        const envelope = await auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: { x: 1 },
+            sphere: "circle",
+        });
+        // Reconstruct what the server would canonicalize-and-verify.
+        const { proof, ...unsignedWithEmptyProof } = envelope;
+        const unsigned = {
+            ...unsignedWithEmptyProof,
+            proof: { ...proof, proofValue: "" },
+        };
+        const bytes = new TextEncoder().encode(canonical(unsigned));
+        const sig = base64urlDecode(envelope.proof.proofValue);
+        assert.ok(ed25519Verify(sig, bytes, id.circle.publicKey), "envelope signed with sphere 'circle' must verify under circle.publicKey");
+    });
+});
+//# sourceMappingURL=envelope.test.js.map

package/dist/test/ethos-first-edition.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ethos-first-edition.test.d.ts.map