@lemmaoracle/seal 0.1.1

package/README.md

@@ -0,0 +1,123 @@
+# @lemmaoracle/seal
+
+ZK auth circuit for **Proof-based sign-in** to the Lemma developer dashboard.
+
+`seal` lets a developer prove they hold a valid Lemma API key **without
+revealing the key**. It is a [zero-knowledge proof](https://lemma.frame00.com)
+of the pre-image of the key's SHA-256 hash.
+
+## How it works
+
+The dashboard's sign-in flow:
+
+1. The dashboard BFF issues a challenge `nonce`.
+2. The developer generates a `seal` proof: it proves knowledge of the
+   API key whose SHA-256 hash equals the `key_hash` stored in the
+   workers `api_keys` table, bound to that `nonce`.
+3. The BFF verifies the proof, reads the attested `key_hash`, looks it
+   up in `api_keys`, and resolves the caller's `scope_id`.
+4. The BFF issues a session token tied to the scope.
+
+The proof reveals only the `key_hash` (already public, since it is what
+the API stores) and the `nonce` — never the API key itself.
+
+> Proof-based sign-in requires an existing API key. First-time users
+> onboard via GitHub OAuth, which issues their first key.
+
+## Package layout
+
+```
+seal/
+├── circuits/
+│   ├── src/seal-identity.circom   Circuit: SHA-256 pre-image proof
+│   ├── src/seal-identity.test.ts  Circuit witness tests (needs a build)
+│   └── scripts/build.sh           Compile circom → wasm + groth16 setup
+├── scripts/
+│   ├── register-circuit.ts        Pin artifacts to IPFS, register via SDK
+│   └── setup-toolchain.sh         Install Rust + circom
+├── src/                           TypeScript proof helpers (published)
+│   ├── bits.ts                    API key ↔ circuit signal conversions
+│   ├── proof.ts                   generateSealProof / verifySealProof
+│   └── index.ts                   Public API
+└── .env.example                   Credentials for register-circuit.ts
+```
+
+There is no `normalize/` step: the circuit's witness input is the raw
+API key string (already canonical), so seal uses the existing
+[`passthrough-v1`](../passthrough) schema rather than a bespoke
+normalizer.
+
+`seal` is a **reference definition**. It is published to npm so
+developers can generate proofs; it is *not* imported by `workers` or the
+dashboard at runtime — the circuit reaches them through the normal
+Lemma circuit-registration path.
+
+## The circuit
+
+`seal-identity.circom` proves `SHA-256(apiKey) == keyHash`:
+
+- **Private input** — `keyBits[512]`: the 64-byte ASCII API key as bits.
+  Lemma keys are 32 random bytes rendered as 64 hex characters (see the
+  workers `generate_api_key.js`).
+- **Public input** — `nonce`: the dashboard challenge, bound into the
+  constraint system for replay protection.
+- **Public output** — `keyHash[256]`: the SHA-256 digest bits.
+
+The hashing matches the workers `middleware/auth.ts`
+(`SHA-256(utf8_bytes(apiKey))`), so a proof's `keyHash` is directly
+comparable to `api_keys.key_hash`.
+
+## Build the circuit
+
+The circom toolchain is **not** required to install or test this package
+— only to compile the circuit and run `register-circuit.ts`.
+
+```bash
+# One-time: install Rust + circom (≈ a few minutes)
+./scripts/setup-toolchain.sh
+
+# Compile → build/seal-identity_js/seal-identity.wasm + _final.zkey
+cd circuits && npm install && npm run build
+```
+
+`build.sh` downloads the 2^17 Hermez powers-of-tau file (~290 MB) on
+first run — SHA-256 over a 512-bit pre-image is ~60k constraints.
+
+## Register the circuit
+
+```bash
+cp .env.example .env        # then fill in LEMMA_API_KEY + PINATA_* keys
+npm run register:circuit
+```
+
+This pins the `.wasm` / `.zkey` to IPFS via Pinata and registers a
+`CircuitMeta` (`circuitId: seal-identity-v1`, `schema: passthrough-v1`,
+off-chain `groth16-bn254-snarkjs` verifier) with the workers API. The
+dashboard BFF then fetches verification params at runtime via
+`GET /v1/circuits/seal-identity-v1`.
+
+## Generate a proof (developer usage)
+
+```ts
+import { generateSealProof } from "@lemmaoracle/seal";
+
+const { proof, publicSignals, keyHash } = await generateSealProof(
+  { apiKey: process.env.LEMMA_API_KEY!, nonce: challengeNonce },
+  { wasm: "seal-identity.wasm", zkey: "seal-identity_final.zkey" },
+);
+// POST { proof, publicSignals } to the dashboard sign-in endpoint.
+```
+
+## Scripts
+
+| Command                   | Description                                |
+| :------------------------ | :----------------------------------------- |
+| `npm run build`           | Compile the TypeScript proof helpers       |
+| `npm test`                | Run the pure unit tests (no toolchain)     |
+| `npm run build:circuit`   | Compile the circom circuit                 |
+| `npm run test:circuit`    | Run circuit witness tests (needs a build)  |
+| `npm run register:circuit`| Pin artifacts to IPFS and register via SDK |
+
+## License
+
+MIT

package/circuits/scripts/build.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+#
+# Compile the seal-identity circuit and run the groth16 trusted setup.
+# Prerequisite: circom + the circuits/ npm dependencies — install them
+# with ../scripts/setup-toolchain.sh.
+#
+set -euo pipefail
+
+CIRCUIT_NAME="seal-identity"
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+SRC_DIR="$SCRIPT_DIR/src"
+BUILD_DIR="$SCRIPT_DIR/build"
+PTAU_DIR="$BUILD_DIR/ptau"
+CIRCOMLIB_DIR="$SCRIPT_DIR/node_modules"
+SNARKJS="npx snarkjs"
+
+# SHA-256 over a 512-bit pre-image compiles to ~60k R1CS constraints
+# (two 512-bit blocks), so phase-1 powers of tau must cover 2^17.
+PTAU_POWER=17
+PTAU="$PTAU_DIR/pot${PTAU_POWER}_final.ptau"
+PTAU_URL="https://storage.googleapis.com/zkevm/ptau/powersOfTau28_hez_final_${PTAU_POWER}.ptau"
+
+mkdir -p "$BUILD_DIR" "$PTAU_DIR"
+
+command -v circom >/dev/null 2>&1 || {
+  echo "✗ circom not found — run ../scripts/setup-toolchain.sh first" >&2
+  exit 1
+}
+
+echo "→ compiling $CIRCUIT_NAME"
+circom "$SRC_DIR/$CIRCUIT_NAME.circom" \
+  --r1cs \
+  --wasm \
+  --sym \
+  -l "$CIRCOMLIB_DIR" \
+  -o "$BUILD_DIR"
+
+echo "→ constraint info"
+$SNARKJS r1cs info "$BUILD_DIR/$CIRCUIT_NAME.r1cs"
+
+# Phase 1 — powers of tau. The 2^17 file is ~290 MB; downloading the
+# pre-generated Hermez ceremony output is far faster and safer than
+# generating one locally.
+if [ ! -f "$PTAU" ]; then
+  echo "→ downloading powers of tau (2^${PTAU_POWER})"
+  curl -fL "$PTAU_URL" -o "$PTAU"
+fi
+
+echo "→ groth16 setup"
+$SNARKJS groth16 setup \
+  "$BUILD_DIR/$CIRCUIT_NAME.r1cs" \
+  "$PTAU" \
+  "$BUILD_DIR/${CIRCUIT_NAME}_0000.zkey"
+
+$SNARKJS zkey contribute \
+  "$BUILD_DIR/${CIRCUIT_NAME}_0000.zkey" \
+  "$BUILD_DIR/${CIRCUIT_NAME}_final.zkey" \
+  --name="lemma seal-identity" -v -e="lemma seal-identity $(date +%s)"
+
+echo "→ exporting verification key"
+$SNARKJS zkey export verificationkey \
+  "$BUILD_DIR/${CIRCUIT_NAME}_final.zkey" \
+  "$BUILD_DIR/${CIRCUIT_NAME}_vkey.json"
+
+echo "✓ $CIRCUIT_NAME built → $BUILD_DIR"

package/circuits/src/seal-identity.circom

@@ -0,0 +1,65 @@
+pragma circom 2.1.0;
+
+include "circomlib/circuits/sha256/sha256.circom";
+
+/**
+ * SealIdentity — Proof-based sign-in for the Lemma developer dashboard.
+ *
+ * Proves knowledge of the pre-image of an API key hash without revealing
+ * the key. The pre-image is the raw API key string; the hash is the
+ * SHA-256 `key_hash` stored in the workers `api_keys` D1 table.
+ *
+ * This matches the hashing in workers `middleware/auth.ts`:
+ *   key_hash = SHA-256( utf8_bytes(apiKey) )
+ *
+ * Lemma API keys are 32 random bytes rendered as a 64-character
+ * lowercase hex string (see workers `generate_api_key.js`), so the
+ * SHA-256 pre-image is exactly 64 ASCII bytes = 512 bits.
+ *
+ * Private input:
+ *   keyBits[512]   Bit decomposition of the 64-byte ASCII API key,
+ *                  most-significant-bit first within each byte.
+ *
+ * Public input:
+ *   nonce          Dashboard-issued challenge nonce. Bound into the
+ *                  constraint system so a proof cannot be replayed
+ *                  against a different challenge.
+ *
+ * Public output:
+ *   keyHash[256]   SHA-256 digest bits. The dashboard BFF reassembles
+ *                  these into the hex `key_hash` and looks it up in
+ *                  `api_keys` to resolve the caller's `scope_id`.
+ */
+template SealIdentity(keyBytes) {
+    var keyBitLen = keyBytes * 8;
+
+    signal input keyBits[keyBitLen];
+    signal input nonce;
+    signal output keyHash[256];
+
+    // Constrain every pre-image bit to be boolean. Without this a
+    // malicious prover could feed non-binary field values into the
+    // SHA-256 gadget and forge a witness.
+    for (var i = 0; i < keyBitLen; i++) {
+        keyBits[i] * (keyBits[i] - 1) === 0;
+    }
+
+    // SHA-256 over the API key bytes. circomlib's Sha256 handles message
+    // padding internally; a 512-bit pre-image spans two 512-bit blocks.
+    component sha = Sha256(keyBitLen);
+    for (var i = 0; i < keyBitLen; i++) {
+        sha.in[i] <== keyBits[i];
+    }
+    for (var i = 0; i < 256; i++) {
+        keyHash[i] <== sha.out[i];
+    }
+
+    // Bind the challenge nonce into the constraint system. The squaring
+    // is otherwise meaningless — its only purpose is to make `nonce` a
+    // constrained public signal, so the verifier knows the proof was
+    // generated for this specific challenge.
+    signal nonceBinding;
+    nonceBinding <== nonce * nonce;
+}
+
+component main {public [nonce]} = SealIdentity(64);

package/dist/bits.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bit-level conversions between API key strings, circuit witness
+ * signals, and SHA-256 hashes. Pure and dependency-free.
+ */
+import type { Bit } from "./types.js";
+/** The seal circuit's fixed pre-image length: a 64-byte ASCII API key. */
+export declare const SEAL_KEY_BYTES = 64;
+/** The seal circuit's pre-image bit length (512). */
+export declare const SEAL_KEY_BITS: number;
+/**
+ * Convert a raw API key string into the `keyBits` witness signal — the
+ * UTF-8 bytes of the key, MSB-first per byte.
+ *
+ * Throws if the key is not exactly {@link SEAL_KEY_BYTES} ASCII bytes,
+ * since the circuit's pre-image length is fixed.
+ */
+export declare const apiKeyToBits: (apiKey: string) => ReadonlyArray<Bit>;
+/**
+ * Reassemble the circuit's 256-bit `keyHash` public output into the
+ * lowercase hex `key_hash` string stored in the `api_keys` table.
+ */
+export declare const hashBitsToHex: (bits: ReadonlyArray<string | number>) => string;
+//# sourceMappingURL=bits.d.ts.map

package/dist/bits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bits.d.ts","sourceRoot":"","sources":["../src/bits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC,0EAA0E;AAC1E,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,qDAAqD;AACrD,eAAO,MAAM,aAAa,QAAqB,CAAC;AAShD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,KAAG,aAAa,CAAC,GAAG,CAS9D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,KACnC,MAKO,CAAC"}

package/dist/bits.js

@@ -0,0 +1,38 @@
+/**
+ * Bit-level conversions between API key strings, circuit witness
+ * signals, and SHA-256 hashes. Pure and dependency-free.
+ */
+/** The seal circuit's fixed pre-image length: a 64-byte ASCII API key. */
+export const SEAL_KEY_BYTES = 64;
+/** The seal circuit's pre-image bit length (512). */
+export const SEAL_KEY_BITS = SEAL_KEY_BYTES * 8;
+/**
+ * Decompose a byte into 8 bits, most-significant-bit first — the bit
+ * order circomlib's SHA-256 gadget expects.
+ */
+const byteToBits = (byte) => Array.from({ length: 8 }, (_, i) => ((byte >> (7 - i)) & 1));
+/**
+ * Convert a raw API key string into the `keyBits` witness signal — the
+ * UTF-8 bytes of the key, MSB-first per byte.
+ *
+ * Throws if the key is not exactly {@link SEAL_KEY_BYTES} ASCII bytes,
+ * since the circuit's pre-image length is fixed.
+ */
+export const apiKeyToBits = (apiKey) => {
+    const bytes = new TextEncoder().encode(apiKey);
+    return bytes.length === SEAL_KEY_BYTES
+        ? [...bytes].flatMap(byteToBits)
+        : (() => {
+            throw new Error(`seal: API key must be ${SEAL_KEY_BYTES} bytes, got ${bytes.length}`);
+        })();
+};
+/**
+ * Reassemble the circuit's 256-bit `keyHash` public output into the
+ * lowercase hex `key_hash` string stored in the `api_keys` table.
+ */
+export const hashBitsToHex = (bits) => bits.length === 256
+    ? BigInt(`0b${bits.map(String).join("")}`).toString(16).padStart(64, "0")
+    : (() => {
+        throw new Error(`seal: keyHash must be 256 bits, got ${bits.length}`);
+    })();
+//# sourceMappingURL=bits.js.map

package/dist/bits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bits.js","sourceRoot":"","sources":["../src/bits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC,qDAAqD;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,cAAc,GAAG,CAAC,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,GAAG,CAAC,IAAY,EAAsB,EAAE,CACtD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAO,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAQ,CAAC,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAc,EAAsB,EAAE;IACjE,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,MAAM,KAAK,cAAc;QACpC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;QAChC,CAAC,CAAC,CAAC,GAAG,EAAE;YACJ,MAAM,IAAI,KAAK,CACb,yBAAyB,cAAc,eAAe,KAAK,CAAC,MAAM,EAAE,CACrE,CAAC;QACJ,CAAC,CAAC,EAAE,CAAC;AACX,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAoC,EAC5B,EAAE,CACV,IAAI,CAAC,MAAM,KAAK,GAAG;IACjB,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;IACzE,CAAC,CAAC,CAAC,GAAG,EAAE;QACJ,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACxE,CAAC,CAAC,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @lemmaoracle/seal — ZK auth circuit for Lemma dashboard sign-in.
+ *
+ * `seal` lets a developer prove knowledge of their Lemma API key
+ * without revealing it. The dashboard BFF issues a challenge nonce, the
+ * developer generates a proof, and the BFF resolves the attested
+ * SHA-256 `key_hash` to a `scope_id`.
+ *
+ * The circuit (`circuits/src/seal-identity.circom`) is registered with
+ * the Lemma workers API as a normal circuit resource. This package is a
+ * reference definition: it is published for developers to generate
+ * proofs and is not imported by workers or the dashboard at runtime.
+ */
+export type { Bit, SealArtifacts, SealProof, SealProofInput, } from "./types.js";
+export { SEAL_KEY_BYTES, SEAL_KEY_BITS, apiKeyToBits, hashBitsToHex, } from "./bits.js";
+export { generateSealProof, verifySealProof } from "./proof.js";
+/** The circuit id under which seal is registered with the Lemma API. */
+export declare const SEAL_CIRCUIT_ID = "seal-identity-v1";
+/** The schema the seal circuit is registered against. */
+export declare const SEAL_SCHEMA = "passthrough-v1";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,YAAY,EACV,GAAG,EACH,aAAa,EACb,SAAS,EACT,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEhE,wEAAwE;AACxE,eAAO,MAAM,eAAe,qBAAqB,CAAC;AAElD,yDAAyD;AACzD,eAAO,MAAM,WAAW,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @lemmaoracle/seal — ZK auth circuit for Lemma dashboard sign-in.
+ *
+ * `seal` lets a developer prove knowledge of their Lemma API key
+ * without revealing it. The dashboard BFF issues a challenge nonce, the
+ * developer generates a proof, and the BFF resolves the attested
+ * SHA-256 `key_hash` to a `scope_id`.
+ *
+ * The circuit (`circuits/src/seal-identity.circom`) is registered with
+ * the Lemma workers API as a normal circuit resource. This package is a
+ * reference definition: it is published for developers to generate
+ * proofs and is not imported by workers or the dashboard at runtime.
+ */
+export { SEAL_KEY_BYTES, SEAL_KEY_BITS, apiKeyToBits, hashBitsToHex, } from "./bits.js";
+export { generateSealProof, verifySealProof } from "./proof.js";
+/** The circuit id under which seal is registered with the Lemma API. */
+export const SEAL_CIRCUIT_ID = "seal-identity-v1";
+/** The schema the seal circuit is registered against. */
+export const SEAL_SCHEMA = "passthrough-v1";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEhE,wEAAwE;AACxE,MAAM,CAAC,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAElD,yDAAyD;AACzD,MAAM,CAAC,MAAM,WAAW,GAAG,gBAAgB,CAAC"}

package/dist/proof.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Seal proof generation and verification.
+ *
+ * Dashboard sign-in flow:
+ *   1. The BFF issues a challenge `nonce`.
+ *   2. The developer runs {@link generateSealProof} with their API key.
+ *   3. The BFF runs {@link verifySealProof} and reads the attested
+ *      `keyHash` to resolve the caller's scope.
+ *
+ * snarkjs is imported lazily so that consumers who only need the pure
+ * bit helpers ({@link apiKeyToBits} etc.) do not pay for it.
+ */
+import type { SealArtifacts, SealProof, SealProofInput } from "./types.js";
+/**
+ * Generate a groth16 proof that the caller knows the API key whose
+ * SHA-256 hash is `keyHash`, bound to the given challenge `nonce`.
+ *
+ * Requires the compiled circuit artifacts — build them with
+ * `npm run build` in `packages/seal/circuits` (see the package README).
+ */
+export declare const generateSealProof: (input: SealProofInput, artifacts: SealArtifacts) => Promise<SealProof>;
+/**
+ * Verify a seal proof against the circuit verification key. Resolves to
+ * the attested `keyHash` and `nonce` on success, or `null` if invalid.
+ */
+export declare const verifySealProof: (proof: SealProof, verificationKey: Readonly<Record<string, unknown>>) => Promise<Readonly<{
+    keyHash: string;
+    nonce: string;
+}> | null>;
+//# sourceMappingURL=proof.d.ts.map

package/dist/proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof.d.ts","sourceRoot":"","sources":["../src/proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAK3E;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,cAAc,EACrB,WAAW,aAAa,KACvB,OAAO,CAAC,SAAS,CAgBnB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,SAAS,EAChB,iBAAiB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KACjD,OAAO,CAAC,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAa7D,CAAC"}

package/dist/proof.js

@@ -0,0 +1,50 @@
+/**
+ * Seal proof generation and verification.
+ *
+ * Dashboard sign-in flow:
+ *   1. The BFF issues a challenge `nonce`.
+ *   2. The developer runs {@link generateSealProof} with their API key.
+ *   3. The BFF runs {@link verifySealProof} and reads the attested
+ *      `keyHash` to resolve the caller's scope.
+ *
+ * snarkjs is imported lazily so that consumers who only need the pure
+ * bit helpers ({@link apiKeyToBits} etc.) do not pay for it.
+ */
+import { apiKeyToBits, hashBitsToHex } from "./bits.js";
+/** Number of `keyHash` bits at the head of the public signal vector. */
+const KEY_HASH_BITS = 256;
+/**
+ * Generate a groth16 proof that the caller knows the API key whose
+ * SHA-256 hash is `keyHash`, bound to the given challenge `nonce`.
+ *
+ * Requires the compiled circuit artifacts — build them with
+ * `npm run build` in `packages/seal/circuits` (see the package README).
+ */
+export const generateSealProof = async (input, artifacts) => {
+    const { groth16 } = await import("snarkjs");
+    const witness = {
+        keyBits: apiKeyToBits(input.apiKey).map(Number),
+        nonce: input.nonce,
+    };
+    const { proof, publicSignals } = await groth16.fullProve(witness, artifacts.wasm, artifacts.zkey);
+    return {
+        proof,
+        publicSignals,
+        keyHash: hashBitsToHex(publicSignals.slice(0, KEY_HASH_BITS)),
+    };
+};
+/**
+ * Verify a seal proof against the circuit verification key. Resolves to
+ * the attested `keyHash` and `nonce` on success, or `null` if invalid.
+ */
+export const verifySealProof = async (proof, verificationKey) => {
+    const { groth16 } = await import("snarkjs");
+    const ok = await groth16.verify(verificationKey, [...proof.publicSignals], proof.proof);
+    return ok
+        ? {
+            keyHash: hashBitsToHex(proof.publicSignals.slice(0, KEY_HASH_BITS)),
+            nonce: proof.publicSignals[KEY_HASH_BITS] ?? "",
+        }
+        : null;
+};
+//# sourceMappingURL=proof.js.map

package/dist/proof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof.js","sourceRoot":"","sources":["../src/proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGxD,wEAAwE;AACxE,MAAM,aAAa,GAAG,GAAG,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,KAAqB,EACrB,SAAwB,EACJ,EAAE;IACtB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAmB;QAC9B,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;QAC/C,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC;IACF,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM,OAAO,CAAC,SAAS,CACtD,OAAO,EACP,SAAS,CAAC,IAAI,EACd,SAAS,CAAC,IAAI,CACf,CAAC;IACF,OAAO;QACL,KAAK;QACL,aAAa;QACb,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;KAC9D,CAAC;AACJ,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,KAAgB,EAChB,eAAkD,EACY,EAAE;IAChE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5C,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,MAAM,CAC7B,eAAe,EACf,CAAC,GAAG,KAAK,CAAC,aAAa,CAAC,EACxB,KAAK,CAAC,KAAK,CACZ,CAAC;IACF,OAAO,EAAE;QACP,CAAC,CAAC;YACE,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;YACnE,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,aAAa,CAAC,IAAI,EAAE;SAChD;QACH,CAAC,CAAC,IAAI,CAAC;AACX,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @lemmaoracle/seal — public types for generating dashboard sign-in proofs.
+ */
+import type { Groth16Proof } from "snarkjs";
+/** A single bit (0 or 1). */
+export type Bit = 0 | 1;
+/** Inputs required to generate a seal sign-in proof. */
+export type SealProofInput = Readonly<{
+    /** The raw API key string — a 64-character lowercase hex string. */
+    apiKey: string;
+    /** The dashboard-issued challenge nonce, as a decimal string. */
+    nonce: string;
+}>;
+/** Filesystem paths (or URLs) of the compiled circuit artifacts. */
+export type SealArtifacts = Readonly<{
+    /** Path/URL to `seal-identity.wasm`. */
+    wasm: string;
+    /** Path/URL to `seal-identity_final.zkey`. */
+    zkey: string;
+}>;
+/** A groth16 proof together with its public signals. */
+export type SealProof = Readonly<{
+    /** The groth16 proof object (snarkjs shape). */
+    proof: Groth16Proof;
+    /** Public signals: the 256 `keyHash` bits followed by `nonce`. */
+    publicSignals: ReadonlyArray<string>;
+    /** The SHA-256 `key_hash` (64-char hex) this proof attests to. */
+    keyHash: string;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,6BAA6B;AAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;AAExB,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAAC;AAEH,wDAAwD;AACxD,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,gDAAgD;IAChD,KAAK,EAAE,YAAY,CAAC;IACpB,kEAAkE;IAClE,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * @lemmaoracle/seal — public types for generating dashboard sign-in proofs.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/vkey.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The groth16 verification key for seal-identity-v1.
+ *
+ * This is public information — it can only verify proofs, not generate them.
+ * Imported as a static JSON module — Vite / Astro will inline it at build
+ * time, so no filesystem access is needed at runtime (Cloudflare Workers).
+ */
+declare const _default: Readonly<Record<string, unknown>>;
+export default _default;
+//# sourceMappingURL=vkey.d.ts.map

package/dist/vkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vkey.d.ts","sourceRoot":"","sources":["../src/vkey.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;wBAIoB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAAxD,wBAAyD"}

package/dist/vkey.js

@@ -0,0 +1,10 @@
+/**
+ * The groth16 verification key for seal-identity-v1.
+ *
+ * This is public information — it can only verify proofs, not generate them.
+ * Imported as a static JSON module — Vite / Astro will inline it at build
+ * time, so no filesystem access is needed at runtime (Cloudflare Workers).
+ */
+import vkey from "./vkeys/seal-identity-v1.json" with { type: "json" };
+export default vkey;
+//# sourceMappingURL=vkey.js.map

package/dist/vkey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vkey.js","sourceRoot":"","sources":["../src/vkey.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,IAAI,MAAM,+BAA+B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAEvE,eAAe,IAAyC,CAAC"}