@docstack/abe 0.1.0

package/LICENSE

@@ -0,0 +1,10 @@
+Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
+
+Copyright (c) Onyx <hello@onyx.ac> (https://onyx.ac)
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+International License. You are free to share and adapt this work, including
+commercially, provided you give appropriate attribution and distribute any
+derivative works under the same license.
+
+Full legal text: https://creativecommons.org/licenses/by-sa/4.0/legalcode

package/README.md

@@ -0,0 +1,66 @@
+[![npm](https://img.shields.io/npm/v/@docstack/abe)](https://www.npmjs.com/package/@docstack/abe)
+[![Docs](https://img.shields.io/badge/docs-onyx--og.github.io-blue)](https://onyx-og.github.io/docstack/docs/guides/access-scopes)
+[![License](https://img.shields.io/badge/license-CC--BY--SA--4.0-lightgrey)](https://github.com/onyx-og/docstack/blob/main/LICENSE.md)
+
+# @docstack/abe
+
+**The cryptography behind DocStack access scopes.**
+
+CP-ABE, the AC17 scheme, from [rabe](https://github.com/Fraunhofer-AISEC/rabe) compiled to WASM, with the policy normaliser and the authority helpers that mint keys and seal scope content keys. `@docstack/client` depends on it and loads it lazily, only when a stack declares scopes; application code on a device never imports it.
+
+An access scope is a named set of content whose encrypted fields seal under one 32-byte content key, and that key is sealed under an attribute policy such as `("role:manager" and "dept:sales") or "clearance:secret"`. A device whose attribute key satisfies the policy opens the scope; one whose key does not holds the same ciphertext and reads `null`. Denial is decryption failure, not a check, so it binds the device owner too.
+
+## Two halves, one module
+
+**Authority half**: runs where the application controls it, its server, an admin ceremony, a script. Master keys never belong on end-user devices.
+
+```typescript
+import { setup, keygen, wrapCek } from '@docstack/abe';
+
+const { pk, msk } = await setup();                    // once; keep msk secret, pk may be public
+const aliceKey = await keygen(msk, ['role:hr', 'dept:people']);
+const sealed = await wrapCek(pk, '"role:hr" or "clearance:exec"', contentKey);   // 32 bytes in, opaque blob out
+```
+
+In practice `ClientStack.buildAccessScope({ scopeId, policyString, pk })` from `@docstack/client` calls `wrapCek` for you and returns a complete `~AccessScope` document: a fresh content key sealed under the policy, its key id, and a per-scope canary. Ship that document in an application patch and every device holds it.
+
+**Client half**: the one call the engine makes.
+
+```typescript
+import { decryptCek } from '@docstack/abe';
+
+const cek = await decryptCek(attributeKey, sealed);   // Uint8Array, or null when the policy is not satisfied
+```
+
+## Policies
+
+```typescript
+import { normalizePolicy, parsePolicy, policyAttributes } from '@docstack/abe';
+
+normalizePolicy('"a" and "b" and "c" and "d"');   // '(("a" and "b") and ("c" and "d"))'
+policyAttributes('("role:hr" or "clearance:exec")'); // ['role:hr', 'clearance:exec']
+```
+
+Formulas are monotone: `and`, `or`, parentheses, `"kind:value"` literals. No negation, no code. The scheme's converter needs balanced parentheses and panics on long unbalanced `and` chains, so every sealing call normalises the formula first; `normalizePolicy` throws on `not`.
+
+## Keys and blobs are opaque
+
+Every key and ciphertext is a string. rabe serialises 64-bit limbs that do not survive a JavaScript JSON round-trip, so store and transport these blobs verbatim and never parse them.
+
+## Status
+
+Experimental cryptography, unaudited. rabe's BN254 backend carries roughly a 100-bit modern security margin; an audit gates any production claim. The reasoning, the alternatives measured and the residual risks are in [ADR-0045](https://github.com/onyx-og/docstack/blob/main/specs/adr/0045-access-control-is-cryptographic-cp-abe-scopes-beside-the-engine.md) and the [threat model](https://onyx-og.github.io/docstack/docs/concepts/access-control/threat-model).
+
+## Building from source
+
+The WASM under `src/wasm` is vendored and regenerated by `npm run build:wasm`, which needs the Rust toolchain with the `wasm32-unknown-unknown` target and `wasm-bindgen-cli` matching the version in `rust/Cargo.lock`. `npm run build` compiles the TypeScript and copies the vendored artifacts into `lib/`; `npm test` runs a smoke test through the WASM.
+
+## Documentation
+
+- [Scope your data](https://onyx-og.github.io/docstack/docs/guides/access-scopes), the guide
+- [Access control](https://onyx-og.github.io/docstack/docs/concepts/access-control/), the model, its formula language and its limits
+- [API reference](https://onyx-og.github.io/docstack/docs/api/abe/)
+
+## License
+
+[CC-BY-SA-4.0](https://github.com/onyx-og/docstack/blob/main/LICENSE.md) · © Onyx AC, LLC. rabe is licensed under the MIT license.

package/lib/index.d.ts

@@ -0,0 +1,25 @@
+export { normalizePolicy, parsePolicy, policyAttributes } from "./policy.js";
+export type { PolicyNode } from "./policy.js";
+/** Authority: mints the master key pair. Returns opaque `pk` (public) and `msk` (SECRET) blobs. */
+export declare const setup: () => Promise<{
+    pk: string;
+    msk: string;
+}>;
+/**
+ * Authority: issues a user's attribute secret key — their attributes embedded
+ * in the key material itself. The returned blob is the `attributeKey` the
+ * consumer's infrastructure hands to that user's devices (spec 02 §4).
+ */
+export declare const keygen: (msk: string, attributes: string[]) => Promise<string>;
+/**
+ * Authority: seals a scope's 32-byte CEK under a policy formula. The formula
+ * is normalized first (balanced parenthesization — rabe's converter panics on
+ * long unbalanced AND-chains), so authors write it naturally.
+ */
+export declare const wrapCek: (pk: string, policy: string, cek: Uint8Array) => Promise<string>;
+/**
+ * Client: attempts a scope's CEK with the session's attribute key.
+ * `null` means the key does not satisfy the scope's policy — access denial as
+ * decryption failure, the whole point of the architecture.
+ */
+export declare const decryptCek: (attributeKey: string, wrappedCek: string) => Promise<Uint8Array | null>;

package/lib/index.js

@@ -0,0 +1,63 @@
+/**
+ * @docstack/abe — CP-ABE (AC17, the FAME scheme) for DocStack access scopes.
+ *
+ * rabe (Fraunhofer AISEC) compiled to WASM; gate ruling ADR-0045. Every key
+ * and ciphertext is an OPAQUE string: rabe-bn serializes u64 limbs that do not
+ * survive a JavaScript JSON round-trip (found the hard way in the spike), so
+ * callers store and transport these blobs verbatim and never parse them.
+ *
+ * Two halves share the module because they share the WASM:
+ * - **Authority half** (`setup`, `keygen`, `wrapCek`): runs where the
+ *   application controls it — its server, an admin ceremony, later the
+ *   docstack-server package. Master keys never belong on end-user devices.
+ * - **Client half** (`decryptCek`): the only call @docstack/client makes.
+ *   Denial is `null` — the mathematics failing IS the access decision.
+ *
+ * EXPERIMENTAL CRYPTOGRAPHY: unaudited (rabe-bn is a fork of an old zcash
+ * BN254 crate, ~100-bit modern margin). An audit gates any production claim.
+ */
+import { ensureAbe } from "./runtime.js";
+import { normalizePolicy } from "./policy.js";
+export { normalizePolicy, parsePolicy, policyAttributes } from "./policy.js";
+/** Authority: mints the master key pair. Returns opaque `pk` (public) and `msk` (SECRET) blobs. */
+export const setup = async () => {
+    const abe = await ensureAbe();
+    const bundle = JSON.parse(abe.setup());
+    return { pk: bundle.pk, msk: bundle.msk };
+};
+/**
+ * Authority: issues a user's attribute secret key — their attributes embedded
+ * in the key material itself. The returned blob is the `attributeKey` the
+ * consumer's infrastructure hands to that user's devices (spec 02 §4).
+ */
+export const keygen = async (msk, attributes) => {
+    if (!attributes.length)
+        throw new Error("keygen requires at least one attribute.");
+    const abe = await ensureAbe();
+    return abe.cp_keygen(msk, JSON.stringify(attributes));
+};
+/**
+ * Authority: seals a scope's 32-byte CEK under a policy formula. The formula
+ * is normalized first (balanced parenthesization — rabe's converter panics on
+ * long unbalanced AND-chains), so authors write it naturally.
+ */
+export const wrapCek = async (pk, policy, cek) => {
+    if (cek.length !== 32)
+        throw new Error(`wrapCek seals 32-byte CEKs; got ${cek.length} bytes.`);
+    const abe = await ensureAbe();
+    return abe.cp_encrypt(pk, normalizePolicy(policy), cek);
+};
+/**
+ * Client: attempts a scope's CEK with the session's attribute key.
+ * `null` means the key does not satisfy the scope's policy — access denial as
+ * decryption failure, the whole point of the architecture.
+ */
+export const decryptCek = async (attributeKey, wrappedCek) => {
+    const abe = await ensureAbe();
+    try {
+        return abe.cp_decrypt(attributeKey, wrappedCek);
+    }
+    catch {
+        return null;
+    }
+};

package/lib/policy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The attribute-policy language and its normalizer.
+ *
+ * DocStack's one access-control language (ADR-0045, spec 02 §1): quoted
+ * attributes composed with `and`/`or` and parentheses — monotone by
+ * construction, no negation, no data-dependence. This module is the ONLY path
+ * a policy string takes into the ABE layer: rabe's MSP converter panics on
+ * unparenthesized AND-chains of length ≥ 3 (characterized in
+ * `spikes/abe/bench/rabe-probe.ts`), so every formula is parsed here and
+ * re-emitted as a fully parenthesized, BALANCED binary tree before it reaches
+ * the scheme. Authors write formulas naturally; the wire form is canonical.
+ */
+export type PolicyNode = {
+    kind: "attr";
+    name: string;
+} | {
+    kind: "op";
+    op: "and" | "or";
+    children: PolicyNode[];
+};
+/** Recursive-descent parse; `and` binds tighter than `or` (the conventional precedence). */
+export declare const parsePolicy: (policy: string) => PolicyNode;
+/**
+ * Parses and re-emits a policy in canonical form: attributes quoted, every
+ * operator application parenthesized, same-op chains balanced. Throws on
+ * anything outside the language — the loud refusal is the API.
+ */
+export declare const normalizePolicy: (policy: string) => string;
+/** The attribute names a formula mentions, in first-appearance order. */
+export declare const policyAttributes: (policy: string) => string[];

package/lib/policy.js

@@ -0,0 +1,145 @@
+/**
+ * The attribute-policy language and its normalizer.
+ *
+ * DocStack's one access-control language (ADR-0045, spec 02 §1): quoted
+ * attributes composed with `and`/`or` and parentheses — monotone by
+ * construction, no negation, no data-dependence. This module is the ONLY path
+ * a policy string takes into the ABE layer: rabe's MSP converter panics on
+ * unparenthesized AND-chains of length ≥ 3 (characterized in
+ * `spikes/abe/bench/rabe-probe.ts`), so every formula is parsed here and
+ * re-emitted as a fully parenthesized, BALANCED binary tree before it reaches
+ * the scheme. Authors write formulas naturally; the wire form is canonical.
+ */
+const tokenize = (policy) => {
+    const tokens = [];
+    let i = 0;
+    while (i < policy.length) {
+        const ch = policy[i];
+        if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+            i++;
+            continue;
+        }
+        if (ch === "(") {
+            tokens.push({ kind: "open" });
+            i++;
+            continue;
+        }
+        if (ch === ")") {
+            tokens.push({ kind: "close" });
+            i++;
+            continue;
+        }
+        if (ch === '"') {
+            const end = policy.indexOf('"', i + 1);
+            if (end === -1)
+                throw new Error(`Policy has an unterminated quoted attribute at position ${i}.`);
+            const name = policy.slice(i + 1, end);
+            if (!name.trim())
+                throw new Error("Policy contains an empty attribute name.");
+            tokens.push({ kind: "attr", name });
+            i = end + 1;
+            continue;
+        }
+        // A bare word: and / or, case-insensitive. Anything else is refused
+        // loudly — including every negation spelling, which the monotone
+        // language deliberately lacks.
+        const match = /^[A-Za-z_][A-Za-z0-9_:-]*/.exec(policy.slice(i));
+        if (!match)
+            throw new Error(`Unexpected character '${ch}' in policy at position ${i}.`);
+        const word = match[0];
+        const lower = word.toLowerCase();
+        if (lower === "and")
+            tokens.push({ kind: "and" });
+        else if (lower === "or")
+            tokens.push({ kind: "or" });
+        else if (lower === "not" || lower === "nand" || lower === "nor") {
+            throw new Error(`Policy operator '${word}' is not part of the monotone language: no negation exists. Model the positive attribute instead.`);
+        }
+        else {
+            throw new Error(`Unquoted word '${word}' in policy: attributes must be double-quoted, e.g. "role:manager".`);
+        }
+        i += word.length;
+    }
+    return tokens;
+};
+/** Recursive-descent parse; `and` binds tighter than `or` (the conventional precedence). */
+export const parsePolicy = (policy) => {
+    const tokens = tokenize(policy);
+    let position = 0;
+    const peek = () => tokens[position];
+    const take = () => tokens[position++];
+    const primary = () => {
+        const token = take();
+        if (!token)
+            throw new Error("Policy ended where an attribute or '(' was expected.");
+        if (token.kind === "attr")
+            return { kind: "attr", name: token.name };
+        if (token.kind === "open") {
+            const node = orExpr();
+            const close = take();
+            if (!close || close.kind !== "close")
+                throw new Error("Policy has an unbalanced '('.");
+            return node;
+        }
+        throw new Error("Policy has an operator where an attribute or '(' was expected.");
+    };
+    const andExpr = () => {
+        const children = [primary()];
+        while (peek()?.kind === "and") {
+            take();
+            children.push(primary());
+        }
+        return children.length === 1 ? children[0] : { kind: "op", op: "and", children };
+    };
+    const orExpr = () => {
+        const children = [andExpr()];
+        while (peek()?.kind === "or") {
+            take();
+            children.push(andExpr());
+        }
+        return children.length === 1 ? children[0] : { kind: "op", op: "or", children };
+    };
+    const root = orExpr();
+    if (position !== tokens.length)
+        throw new Error("Policy has trailing content after a complete formula (an unbalanced ')' or a missing operator).");
+    return root;
+};
+/** Flattens nested same-op nodes so chains balance across author parenthesization. */
+const flatten = (node) => {
+    if (node.kind === "attr")
+        return node;
+    const children = [];
+    for (const child of node.children.map(flatten)) {
+        if (child.kind === "op" && child.op === node.op)
+            children.push(...child.children);
+        else
+            children.push(child);
+    }
+    return { kind: "op", op: node.op, children };
+};
+/** Emits a chain as a balanced binary tree — the shape rabe's converter accepts at any length. */
+const emitBalanced = (nodes, op) => {
+    if (nodes.length === 1)
+        return emit(nodes[0]);
+    const mid = Math.ceil(nodes.length / 2);
+    return `(${emitBalanced(nodes.slice(0, mid), op)} ${op} ${emitBalanced(nodes.slice(mid), op)})`;
+};
+const emit = (node) => node.kind === "attr" ? `"${node.name}"` : emitBalanced(node.children, node.op);
+/**
+ * Parses and re-emits a policy in canonical form: attributes quoted, every
+ * operator application parenthesized, same-op chains balanced. Throws on
+ * anything outside the language — the loud refusal is the API.
+ */
+export const normalizePolicy = (policy) => emit(flatten(parsePolicy(policy)));
+/** The attribute names a formula mentions, in first-appearance order. */
+export const policyAttributes = (policy) => {
+    const seen = new Set();
+    const walk = (node) => {
+        if (node.kind === "attr")
+            seen.add(node.name);
+        else
+            node.children.forEach(walk);
+    };
+    walk(parsePolicy(policy));
+    return [...seen];
+};

package/lib/runtime.d.ts

@@ -0,0 +1,7 @@
+export type AbeApi = {
+    setup(): string;
+    cp_keygen(mskJson: string, attrsJson: string): string;
+    cp_encrypt(pkJson: string, policy: string, plaintext: Uint8Array): string;
+    cp_decrypt(skJson: string, ctJson: string): Uint8Array;
+};
+export declare const ensureAbe: () => Promise<AbeApi>;

package/lib/runtime.js

@@ -0,0 +1,26 @@
+/**
+ * Lazy WASM instantiation. The module bytes ride the bundle base64-embedded
+ * (no fetch, no asset path — every bundler and the browser test harness see
+ * plain JS), but nothing compiles until the first ABE call: a stack that never
+ * touches scopes pays bytes, not startup. Instantiation is ASYNC on purpose —
+ * Chrome caps synchronous WebAssembly compilation on the main thread, so
+ * `initSync` over a 600 KB module is a browser refusal waiting to happen.
+ */
+import init, * as glue from "./wasm/glue.js";
+import { WASM_BASE64 } from "./wasm/bytes.js";
+let ready = null;
+const decode = (b64) => {
+    if (typeof Buffer !== "undefined")
+        return new Uint8Array(Buffer.from(b64, "base64"));
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+};
+export const ensureAbe = () => {
+    if (!ready) {
+        ready = init({ module_or_path: decode(WASM_BASE64) }).then(() => glue);
+    }
+    return ready;
+};

package/lib/wasm/bytes.d.ts

@@ -0,0 +1 @@
+export declare const WASM_BASE64: string;