@cef-ai/vault-sdk 3.3.0 → 4.1.0

package/dist/core/grant-doc.js

@@ -0,0 +1,768 @@
+// src/core/grant-doc.ts
+//
+// The canonical grant document — the bytes a vault owner signs to say "this
+// person holds this role and these scopes on this vault" — and the check that
+// a served signature is theirs.
+//
+// This is the TypeScript mirror of ddc-node's
+// `pkg/compute/vault/grantsig.go` — the implementation moved there from
+// `internal/compute/vault/authz` when the orchestrator became its second
+// reader, and `authz` is now a delegation shim, so the `authz.*` names used
+// throughout these comments all forward to that file. Its whole reason to
+// exist is
+// that `GET /api/v1/vaults/:vaultId/roster/signed` is only worth serving if a
+// party that is NOT vault-api can check it. If every consumer had to
+// re-implement base64 → ed25519 → schema check by hand, most would check the
+// signature and then read the response's own convenience fields, which is a
+// decorative signature: verifying one thing and enforcing another.
+//
+// # Read role and scopes out of the DOCUMENT, never off the response
+//
+// `SignedGrant.role` and `SignedGrant.scopes` are a RENDERING of `doc` that
+// vault-api provides for display. They are deliberately typed as plain
+// strings here, not as `MemberRole`/`ScopeGrants`, so that feeding them
+// straight into code that decides access is awkward rather than natural.
+// `verifySignedRoster` returns `Grant`s decoded from the verified bytes; those
+// are the values to act on.
+//
+// # The document is verified as received, never re-encoded
+//
+// `verifyGrantSig` checks the signature over the exact bytes it was handed.
+// It does NOT rebuild them with `canonicalGrantBytes` and compare: a verifier
+// that re-encodes is checking bytes it just composed itself, and it would
+// start rejecting perfectly valid documents the moment this encoder and the
+// server's drifted by a space. Go's `DecodeGrantDoc` is a reader for the same
+// reason. `canonicalGrantBytes` exists for the SIGNING side (whoever mints a
+// grant must produce bytes vault-api will accept) and for tests.
+//
+// # Mirroring Go's encoder exactly, in the two places it is not obvious
+//
+// 1. `encoding/json` escapes `<`, `>` and `&` as the six-character escapes
+//    `\u003c`, `\u003e`, `\u0026`
+//    (`SetEscapeHTML` defaults to true), plus U+2028/U+2029. `JSON.stringify`
+//    escapes none of them. A scope named `a<b` would otherwise produce
+//    different bytes on the two sides and a signature that never verifies.
+// 2. Go sorts scope names as raw UTF-8 byte strings, which is code-point
+//    order. JavaScript's `<` compares UTF-16 code units, which disagrees for
+//    astral characters: `"😀" < "Ａ"` is true in UTF-16 and false by code
+//    point. `compareCodePoints` below sorts the way Go does.
+//
+// 3. `issuedAt` and `expiresAt` are STRINGS carried verbatim, never `Date`s.
+//    Go's `encoding/json` would trim trailing zeros off a re-marshalled
+//    fraction (`…:56.100Z` → `…:56.1Z`), so neither side may re-format what
+//    the other signed. Whatever string the signer chose is what goes in the
+//    bytes.
+//
+// 4. `expiresAt` IS ALWAYS PRESENT, and "no expiry" is the EMPTY STRING
+//    (`NO_GRANT_EXPIRY`) rather than a dropped key or a `null`. One document
+//    shape, always: omitting the field would make a never-expires grant
+//    byte-identical to a document minted before the field existed, so every
+//    signature already stored would verify as a brand-new unlimited grant.
+//    See `NO_GRANT_EXPIRY`.
+//
+// Both are pinned by golden vectors produced by running the real Go function
+// (see `grant-doc.test.ts`), not by reading its source and guessing.
+//
+// # A GRANT DOCUMENT IS AUTHORITY ONLY WHEN YOU FETCHED IT YOURSELF
+//
+// This mirrors `pkg/compute/vault/grantsig.go`'s rule, and it is the reason
+// `verifySignedRoster` takes a whole roster rather than a loose grant.
+//
+// A verified signature proves the vault owner once signed these bytes. It does
+// NOT prove the grant still stands: revocation deletes the membership row and
+// cannot reach back and unsign a document somebody already saved. `issuedAt`
+// does not change that — a timestamp bounds how OLD a document is, never
+// whether it was WITHDRAWN.
+//
+// So: fetch the signed roster yourself, verify it, and act on what it
+// contains. Absence from a freshly fetched roster is what revocation looks
+// like, and it is the only signal that carries it. Accepting a document a
+// caller HANDS you and authorising them on it is wrong in a way that passes
+// every test — a revoked member's saved grant verifies forever — and checking
+// that its `issuedAt` is recent does not fix it, it only narrows the window.
+import * as ed from "@noble/ed25519";
+// The `./blake2` SUBPATH, not the package root. Both work at runtime, but
+// 14.0.3's root barrel does not re-export either blake2 name to
+// TypeScript (`encodeAddress` and the rest come through fine), so the
+// root import compiles nowhere. `./blake2` is a declared export subpath.
+import { blake2AsHex } from "@polkadot/util-crypto/blake2";
+import { decodeBase64, hexToBytes, strip0xHex } from "./canonical.js";
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+/**
+ * The schema string a CEILING-LESS grant carries inside its signed bytes
+ * (`authz.GrantSchemaV1`). Still emitted, still the common case: a grant that
+ * sets no privacy ceiling is encoded at v1, byte for byte as it always was,
+ * so every signature minted before v2 existed goes on verifying.
+ */
+export const GRANT_SCHEMA = "cere.vault.grant.v1";
+/**
+ * The schema string a ceiling-carrying grant carries (`authz.GrantSchemaV2`).
+ *
+ * A document is v2 if and only if it carries a privacy ceiling. There is no
+ * v2 spelling of "no ceiling" — that is v1, and giving it two spellings is
+ * the ambiguity `NO_GRANT_EXPIRY`'s comment spends a paragraph refusing.
+ *
+ * The version is a FUNCTION of the ceiling rather than an unconditional bump:
+ * bumping it always would change the bytes of every grant, including the
+ * overwhelming majority that sets no ceiling, which is a flag day on every
+ * stored signature. See `canonicalGrantBytesWithCeiling`.
+ */
+export const GRANT_SCHEMA_V2 = "cere.vault.grant.v2";
+/**
+ * The ONE spelling of "no privacy ceiling was ever signed for this
+ * membership" — and it is NOT a synonym for `"public"`.
+ *
+ * It means NOTHING VISIBLE, and that is a decision on the record: a caller
+ * whose ceiling is this sees no memory-graph row at all, because a ceiling
+ * nobody signed is not a ceiling. Picking `"internal"` as the default would
+ * invent an authorisation the vault owner never attested on the axis whose
+ * whole job is disclosure — the same ruling `NO_GRANT_EXPIRY` makes one field
+ * earlier, except that there the failure direction WIDENS an unsigned grant
+ * and here it NARROWS to zero, which is why failing closed is free.
+ *
+ * Selects {@link GRANT_SCHEMA} in the encoder: a grant carrying this is a v1
+ * document, byte for byte.
+ */
+export const NO_PRIVACY_CEILING = "";
+/**
+ * Every ceiling a grant may carry, least to most sensitive — Go's
+ * `validPrivacyCeilings`. {@link NO_PRIVACY_CEILING} is deliberately ABSENT:
+ * it is a legal decoded state (the document is v1) but never a value a caller
+ * may SET, and admitting `""` at the writer would give the state two
+ * spellings.
+ */
+export const PRIVACY_CEILINGS = [
+    "public",
+    "internal",
+    "private",
+    "restricted",
+];
+/** Is `c` a ceiling a v2 grant may carry? The WRITER-side guard. */
+export function isValidPrivacyCeiling(c) {
+    return PRIVACY_CEILINGS.includes(c);
+}
+/** Renders the valid ceilings for an error, as Go's `PrivacyCeilingsList`. */
+function privacyCeilingsList() {
+    const quoted = PRIVACY_CEILINGS.map((c) => `"${c}"`);
+    return quoted.slice(0, -1).join(", ") + " or " + quoted[quoted.length - 1];
+}
+/** Tags a string as a privacy ceiling. The parameter type is the literal
+ *  union, so a misspelling is a compile error and an as-yet-unknown ceiling
+ *  from a newer peer has to be cast deliberately. */
+export function privacyCeiling(c) {
+    return c;
+}
+/**
+ * The header a membership write carries the vault owner's grant signature in
+ * (`authz.GrantSignatureHeader`), hex, with or without an `0x` prefix.
+ *
+ * A HEADER OF ITS OWN, not the wallet auth's `X-Signature`, because the two
+ * cover different bytes: `X-Signature` covers the request BODY and
+ * authenticates the CALLER (who may be an admin acting for the owner), while
+ * this covers the canonical grant document and attests the OWNER's
+ * authorisation of that exact grant. The body of `PUT .../members` is
+ * `{"role":…,"timestamp":…}` — the vault id and the member's key are URL
+ * parameters and never enter the signed bytes — so one owner-signed
+ * `{"role":"admin",…}` would otherwise verify identically for every member of
+ * every vault that owner holds.
+ */
+export const GRANT_SIGNATURE_HEADER = "X-Grant-Signature";
+/**
+ * The header carrying the `issuedAt` the signed document was minted with
+ * (`pkgvault.GrantIssuedAtHeader`).
+ *
+ * vault-api does not RECEIVE the grant document, it REBUILDS it — from the URL
+ * parameters, the body, and the other half read back from its store — and then
+ * checks your signature over what it built. Every field must therefore be
+ * something the server can reproduce, and a mint time is the one thing it
+ * cannot: a server-chosen `now` would never equal yours. So it travels beside
+ * the signature.
+ *
+ * NOT the body's `timestamp`, even though every mutation body already carries
+ * one and the wallet middleware already bounds its skew. The signer and the
+ * sender are different parties: the route admits an admin, but the document
+ * must be signed by the VAULT's wallet, so an admin presents a grant their
+ * owner signed out of band. Binding the mint time to the request body would
+ * make the owner predict the admin's exact timestamp string, and the skew
+ * window would expire their pre-signed grant in five minutes.
+ */
+export const GRANT_ISSUED_AT_HEADER = "X-Grant-Issued-At";
+/**
+ * `auth.CanonicalPubKeyHex`, reproduced: `0x`-prefixed lowercase hex, or the
+ * input UNCHANGED when it is not hex at all.
+ *
+ * THE SERVER APPLIES THIS TO THE URL PARAMETER BEFORE IT BUILDS THE DOCUMENT
+ * (`memberPubkeyParam`), so a signer that skips it produces a perfectly valid
+ * signature over bytes the server never derives — the failure that presents
+ * as a key problem rather than a spelling one. Callers have always been
+ * allowed to pass a bare or upper-case key (the store canonicalises on the
+ * way in), so signing their exact spelling would break the writes that work
+ * today.
+ *
+ * A non-hex value passes through untouched, exactly as Go's does: a malformed
+ * key must reach the server as the caller wrote it and be refused there,
+ * rather than be silently rewritten into a different key here.
+ */
+export function canonicalPubkeyHex(s) {
+    // `normalizeHexKey`: TrimPrefix "0x" THEN TrimPrefix "0X" — one each, in
+    // that order — then lower-case. Reproduced literally rather than as one
+    // regex so the two implementations can be read side by side.
+    let bare = s.startsWith("0x") ? s.slice(2) : s;
+    if (bare.startsWith("0X"))
+        bare = bare.slice(2);
+    bare = bare.toLowerCase();
+    // `bare == ""` and a `hex.DecodeString` failure — which includes an
+    // ODD-LENGTH string — both return the input unchanged.
+    if (bare === "" || bare.length % 2 !== 0 || !/^[0-9a-f]+$/.test(bare))
+        return s;
+    return `0x${bare}`;
+}
+/**
+ * The vault id a wallet key owns — `pkgvault.IDFor`, reproduced.
+ *
+ * `"v-"` + blake2b-128 of the key's CANONICAL HEX SPELLING, as 32 lowercase
+ * hex characters.
+ *
+ * # This is a one-way function, and that is the whole point
+ *
+ * It runs pubkey -> id. It does NOT run backwards, and no amount of holding
+ * an id recovers the key that made it: blake2b-128 is a hash. What a caller
+ * holding only a vault id CAN do is the inverse QUESTION rather than the
+ * inverse function — take a candidate key and ask whether it derives that id.
+ * That single check is what turns `verifySignedRoster` from a consistency
+ * test into a verification, because the id came from outside the response
+ * and the key inside it now has to match something the attacker cannot
+ * choose.
+ *
+ * # Two ways to get this wrong, both of which produce a plausible id
+ *
+ * 1. The key is hashed as its hex TEXT (Go writes `[]byte(walletPubkeyHex)`),
+ *    never as the 32 bytes that text denotes. `@polkadot`'s `blake2AsHex`
+ *    decodes a `0x`-prefixed STRING as hex, so it must be handed encoded
+ *    bytes — passing the spelling straight in silently hashes the wrong
+ *    input.
+ * 2. Because the text is the input, the SPELLING is part of it: `deadbeef`,
+ *    `0xdeadbeef` and `0xDEADBEEF` are three different vault ids in Go.
+ *    Callers have always been allowed any of those spellings, so the
+ *    canonical form is applied first — the same rule the server derives with.
+ *
+ * Both are pinned by golden vectors taken from the running Go function.
+ */
+export function vaultIdFor(walletPubkeyHex) {
+    const canonical = canonicalPubkeyHex(walletPubkeyHex);
+    // `enc.encode` first — see (1) above; `blake2AsHex` returns `0x`-prefixed
+    // hex where Go's `hex.EncodeToString` does not, hence the slice.
+    return `v-${blake2AsHex(enc.encode(canonical), 128).slice(2)}`;
+}
+/**
+ * The ONE spelling of "this membership does not expire": the empty string,
+ * always emitted, never an absent key and never `null`.
+ *
+ * A FIXED SENTINEL so the canonical document has exactly one shape. Two shapes
+ * is how a signature comes to verify against bytes the other side never
+ * builds, and here conditional omission would be worse than ambiguous: a
+ * document that DROPPED `expiresAt` when there is no expiry is byte-identical
+ * to a document minted before the field existed, so every signature already
+ * stored would verify as a brand-new never-expires grant. Emitting `""` makes
+ * those older bytes unbuildable, which is the version gate this change would
+ * otherwise have to spend a new {@link GRANT_SCHEMA} string on.
+ *
+ * The empty string also cannot be mistaken for a moment — no RFC 3339 spelling
+ * is empty — so, unlike a far-future sentinel instant, nothing downstream can
+ * parse it into a date and silently act on the year 9999.
+ */
+export const NO_GRANT_EXPIRY = "";
+/**
+ * Tags a timestamp string as the grant's expiry.
+ *
+ * It does NOT validate: the string is carried into the signed bytes verbatim
+ * and neither side parses or re-formats it, so a check here would be a second
+ * opinion about a value the server rebuilds from what you sent. vault-api DOES
+ * validate — `PUT …/members` 400s an `expiresAt` that is not RFC 3339, because
+ * that value also has to reach a `timestamptz` column — so a malformed expiry
+ * is refused at the one place that can refuse it usefully.
+ *
+ * Pass the SAME string you put in the request body. Formatting a `Date` twice
+ * is how the two copies drift by a trimmed fractional zero.
+ */
+export function grantExpiry(rfc3339) {
+    return rfc3339;
+}
+/**
+ * A signed grant that could not be trusted: the signature does not verify,
+ * the document does not decode, its schema is unknown, or it describes a
+ * different membership from the one it was served under.
+ *
+ * THROWN by {@link verifyGrant}, where one grant IS the whole question and a
+ * failure must stop the caller. REPORTED (and the entry skipped) by
+ * {@link verifySignedRoster}, where the same failure on one entry used to
+ * fail the whole roster for every other member — see that function's doc
+ * comment for the outage that ruling turned out to be. `memberPubkey` names
+ * the entry so an operator can find it.
+ */
+export class GrantVerificationError extends Error {
+    memberPubkey;
+    constructor(message, 
+    /**
+     * The member the failure is about, or `""` when it is about the ENVELOPE
+     * — a missing anchor, a roster for the wrong vault, a malformed shape —
+     * which belongs to no single entry.
+     */
+    memberPubkey = "") {
+        super(message);
+        this.memberPubkey = memberPubkey;
+        this.name = "GrantVerificationError";
+    }
+}
+/**
+ * The exact bytes a CEILING-LESS grant signature covers — v1, byte for byte
+ * as `authz.CanonicalGrantBytes` has always emitted them. Delegates to
+ * {@link canonicalGrantBytesWithCeiling}; see that function for the full
+ * contract, and this file's header for why the version is a function of the
+ * ceiling rather than an unconditional bump.
+ */
+export function canonicalGrantBytes(vaultId, memberPubkey, role, scopes, issuedAt, expiresAt) {
+    return canonicalGrantBytesWithCeiling(vaultId, memberPubkey, role, scopes, issuedAt, expiresAt, NO_PRIVACY_CEILING);
+}
+/**
+ * The encoder, mirroring `authz.CanonicalGrantBytesWithCeiling`. Emits
+ * {@link GRANT_SCHEMA} when the grant sets no privacy ceiling and
+ * {@link GRANT_SCHEMA_V2} when it sets one.
+ *
+ * Every bound value is inside the output: a document proves ONE member's
+ * standing on ONE vault and nothing else. `scopes` is emitted as an ARRAY
+ * sorted by name — not as an object — because the ordering is then this
+ * function's own step and can be tested, where a JSON object would have the
+ * encoder sort the keys and a stability test would pass whatever this code
+ * did.
+ *
+ * An incomplete grant throws rather than producing shorter bytes: a document
+ * naming no vault or no member would verify perfectly and authorise nobody in
+ * particular. `issuedAt` is required on the same grounds — an empty one is a
+ * document with no mint time that verifies exactly as well as one with a mint
+ * time.
+ *
+ * `privacyCeiling` is emitted LAST, after `expiresAt`, and ONLY when set —
+ * `omitempty` in Go, an append here — so a ceiling-less grant is
+ * byte-identical to a v1 document and every signature already stored goes on
+ * matching what this encoder rebuilds.
+ *
+ * The ceiling is REFUSED, never coerced: an unrecognised value throws, because
+ * a document that verifies perfectly and confers a ceiling nobody named is,
+ * on the disclosure axis, the one output this function must never hand back.
+ * {@link NO_PRIVACY_CEILING} is the single exception and is not a value: it
+ * selects v1.
+ *
+ * `issuedAt` has NO DEFAULT on purpose: a `new Date().toISOString()` fallback
+ * would be a hidden clock inside the encoder, and a caller who forgot to pass
+ * one would silently sign a different moment from the one they sent. `scopes`
+ * loses its `= {}` default with it — a default that can never be used, because
+ * a required parameter follows, reads as an option and is not one. `expiresAt`
+ * has none for the sharper version of the same reason: its default would be
+ * "never expires", the one wrong answer that looks right.
+ *
+ * `expiresAt` is the ONE parameter with no emptiness check, because `""` is
+ * {@link NO_GRANT_EXPIRY} — a legal, common, deliberate value rather than a
+ * missing one. `ceiling` shares the exemption for the same reason.
+ */
+export function canonicalGrantBytesWithCeiling(vaultId, memberPubkey, role, scopes, issuedAt, expiresAt, privacyCeiling) {
+    if (vaultId === "")
+        throw new Error("canonical grant: vaultId is required");
+    if (memberPubkey === "")
+        throw new Error("canonical grant: memberPubkey is required");
+    if (role === "")
+        throw new Error("canonical grant: role is required");
+    if (issuedAt === "")
+        throw new Error("canonical grant: issuedAt is required");
+    // The version gate, and the writer-side refusal, in one place: anything
+    // that is neither "no ceiling" nor a recognised class stops here.
+    let schema = GRANT_SCHEMA;
+    if (privacyCeiling !== NO_PRIVACY_CEILING) {
+        if (!isValidPrivacyCeiling(privacyCeiling)) {
+            throw new Error(`canonical grant: privacyCeiling ${JSON.stringify(privacyCeiling)} must be ${privacyCeilingsList()}`);
+        }
+        schema = GRANT_SCHEMA_V2;
+    }
+    const names = Object.keys(scopes).sort(compareCodePoints);
+    const parts = names.map((name) => `{"name":${goString(name)},"level":${goString(scopes[name])}}`);
+    // Hand-assembled rather than `JSON.stringify`d because the field ORDER is
+    // the wire contract (Go emits struct fields in declaration order) and
+    // because `goString` has to do the HTML escaping `JSON.stringify` will not.
+    const doc = `{"schema":${goString(schema)},` +
+        `"vaultId":${goString(vaultId)},` +
+        `"memberPubkey":${goString(memberPubkey)},` +
+        `"role":${goString(role)},` +
+        `"scopes":[${parts.join(",")}],` +
+        `"issuedAt":${goString(issuedAt)},` +
+        `"expiresAt":${goString(expiresAt)}` +
+        // omitempty: the ceiling key is present in a v2 document ONLY. Appending
+        // it unconditionally would give v1 a second spelling and break every
+        // stored signature's rebuild.
+        (privacyCeiling === NO_PRIVACY_CEILING ? "" : `,"privacyCeiling":${goString(privacyCeiling)}`) +
+        "}";
+    return enc.encode(doc);
+}
+/**
+ * Reads a canonical grant document back into its parts, mirroring
+ * `authz.DecodeGrantDoc`. Never re-encodes; the bytes stay the authority.
+ *
+ * Accepts BOTH current schemas — {@link GRANT_SCHEMA} and
+ * {@link GRANT_SCHEMA_V2} — with the field that distinguishes them checked in
+ * both directions (a v1 document carrying a `privacyCeiling` is a forgery
+ * shape; a v2 document without a recognised one has given "no ceiling" a
+ * second spelling). Throws on any other schema and on the same three required
+ * fields the encoder refuses to omit.
+ */
+export function decodeGrantDoc(doc) {
+    if (doc.length === 0)
+        throw new Error("decode grant: empty document");
+    let raw;
+    try {
+        raw = JSON.parse(dec.decode(doc));
+    }
+    catch (err) {
+        throw new Error(`decode grant: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error("decode grant: document is not a JSON object");
+    }
+    const obj = raw;
+    const schema = stringField(obj, "schema");
+    // THE VERSION GATE, AND IT IS TWO-WAY — mirroring `DecodeGrantDoc`'s switch.
+    //
+    // It used to be one equality against one constant. Two schema strings are
+    // current, and the field that distinguishes them must be checked in BOTH
+    // directions, because a JSON reader ignores unknown keys by default:
+    //
+    //   - a v1 document carrying a privacyCeiling key would otherwise decode
+    //     as a clean v1 grant with the field silently dropped. That is a
+    //     forgery shape — the owner attested v1 semantics and somebody
+    //     appended a field — and dropping it quietly is how a reader comes to
+    //     disagree with the bytes it verified.
+    //   - a v2 document with no usable ceiling would otherwise decode to
+    //     NO_PRIVACY_CEILING, giving "no ceiling" a second spelling under a
+    //     schema string that promises one.
+    //
+    // Refusing both is what keeps the schema string an honest description of
+    // the bytes rather than a label. Note the emptiness (not presence) check
+    // on v1: Go unmarshals `"privacyCeiling":""` into the empty string and
+    // treats it as absent, so a v1 document with an EMPTY ceiling key decodes
+    // as v1 here too — matching the bytes Go accepts, not a stricter rule.
+    const rawCeiling = stringField(obj, "privacyCeiling", true);
+    if (schema === GRANT_SCHEMA) {
+        if (rawCeiling !== "") {
+            throw new Error(`decode grant: schema ${JSON.stringify(schema)} carries a privacyCeiling; that is ${JSON.stringify(GRANT_SCHEMA_V2)}`);
+        }
+    }
+    else if (schema === GRANT_SCHEMA_V2) {
+        if (!isValidPrivacyCeiling(rawCeiling)) {
+            throw new Error(`decode grant: schema ${JSON.stringify(schema)} requires a privacyCeiling of ${privacyCeilingsList()}, got ${JSON.stringify(rawCeiling)}`);
+        }
+    }
+    else {
+        throw new Error(`decode grant: schema ${JSON.stringify(schema)} is not ${JSON.stringify(GRANT_SCHEMA)} or ${JSON.stringify(GRANT_SCHEMA_V2)}`);
+    }
+    const vaultId = stringField(obj, "vaultId");
+    const memberPubkey = stringField(obj, "memberPubkey");
+    const role = stringField(obj, "role");
+    if (vaultId === "" || memberPubkey === "" || role === "") {
+        throw new Error("decode grant: vaultId, memberPubkey and role are all required");
+    }
+    // `scopes` is an array in the document and a map here, exactly as Go's
+    // decoder does it: the array exists so the ENCODER's ordering is a testable
+    // step, and a decoder has no ordering left to prove — every consumer of a
+    // decoded grant asks "what level on scope X", which is a map question.
+    const rawScopes = obj.scopes;
+    if (!Array.isArray(rawScopes)) {
+        throw new Error("decode grant: scopes must be an array");
+    }
+    const scopes = {};
+    for (const entry of rawScopes) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw new Error("decode grant: a scope entry is not an object");
+        }
+        const name = stringField(entry, "name");
+        if (name === "")
+            throw new Error("decode grant: a scope with no name");
+        scopes[name] = stringField(entry, "level");
+    }
+    // LAST, because the fields are checked in WIRE ORDER and `issuedAt` is the
+    // last field of the document. Required exactly as Go's decoder requires it:
+    // a document predating the field is REFUSED rather than passed on as a
+    // grant with no mint time.
+    const issuedAt = stringField(obj, "issuedAt");
+    if (issuedAt === "")
+        throw new Error("decode grant: issuedAt is required");
+    // PRESENCE, not emptiness, and the asymmetry with `issuedAt` above is the
+    // point: `""` is NO_GRANT_EXPIRY, a legal value most documents carry, while
+    // an ABSENT key is a document minted before the field existed — one whose
+    // signer attested a standing and never its duration. `stringField` already
+    // refuses absent ("got nothing") and `null` ("got object"), which is exactly
+    // what Go's `raw.ExpiresAt == nil` refuses; an `=== ""` guard here would make
+    // "this membership never expires" undecodable.
+    const expiresAt = stringField(obj, "expiresAt");
+    // v1 decodes to NO_PRIVACY_CEILING — the version gate above has already
+    // proved the key was absent-or-empty for v1 and valid for v2.
+    const ceiling = (schema === GRANT_SCHEMA_V2 ? rawCeiling : "");
+    return { schema, vaultId, memberPubkey, role, scopes, issuedAt, expiresAt, privacyCeiling: ceiling };
+}
+/**
+ * Is `sigHex` `orgWalletPubkeyHex`'s ed25519 signature over `doc`?
+ *
+ * A boolean, not a throw, because nothing here can be undecided: both inputs
+ * are in hand and the check is arithmetic. Malformed inputs (a key or
+ * signature of the wrong length, non-hex) are `false` rather than an
+ * exception, mirroring `authz.VerifyGrantSig` — the caller that needs to tell
+ * "nothing was sent" from "it does not verify" looks at the inputs itself.
+ *
+ * Hex is accepted with or without an `0x` prefix, in either case, because
+ * wallets and SDKs disagree about both.
+ */
+export async function verifyGrantSig(orgWalletPubkeyHex, doc, sigHex) {
+    if (doc.length === 0 || sigHex === "")
+        return false;
+    let pub;
+    let sig;
+    try {
+        pub = hexToBytes(strip0xHex(orgWalletPubkeyHex).toLowerCase());
+        sig = hexToBytes(strip0xHex(sigHex).toLowerCase());
+    }
+    catch {
+        return false;
+    }
+    if (pub.length !== 32 || sig.length !== 64)
+        return false;
+    try {
+        return await ed.verifyAsync(sig, doc, pub);
+    }
+    catch {
+        // @noble throws on a point that is not on the curve; that is a failed
+        // verification, not a caller error.
+        return false;
+    }
+}
+/**
+ * Verifies EVERY grant in a signed roster against the vault owner's key and
+ * returns the grants decoded from the verified bytes.
+ *
+ * This is the whole point of the signed roster: after this call you hold
+ * values that came out of bytes the vault owner signed, and you can throw the
+ * response away. Enforce on the returned `Grant`s — never on
+ * `SignedGrant.role` / `SignedGrant.scopes`, which are vault-api's rendering
+ * of the same document and are not covered by anything you checked.
+ *
+ * Three bindings are checked per entry, and the last two matter as much as
+ * the signature: the document must carry a schema this SDK understands, it
+ * must name the vault the roster is FOR, and it must name the member it was
+ * served UNDER. A document that verifies but describes a different membership
+ * is a valid signature over somebody else's grant — the substitution the
+ * canonical bytes bind all four values to prevent.
+ *
+ * # One unverifiable entry degrades the ENTRY, not the roster
+ *
+ * An entry that fails any of its checks is skipped and reported to
+ * {@link RosterVerifyOptions.onUnverifiableGrant} (when given) rather than
+ * thrown, and the remaining entries are returned. This is deliberate, and it
+ * is the second half of the condition ddc-node's `allowV2GrantMint` hold
+ * names for lifting: the loop this replaces threw on the FIRST bad entry, so
+ * one grant a consumer could not read — a ceiling-carrying v2 under 4.0.0, a
+ * future v3, a corrupt row — made the WHOLE roster fail verification for
+ * every member of that vault. An outage with a bystander list that long is
+ * not fail-closed, it is fail-everyone-else's.
+ *
+ * The envelope is still fail-closed: a roster naming the wrong vault, a
+ * signing key that does not derive the vault, or a malformed roster shape
+ * throws `GrantVerificationError` and NOTHING is returned — until the anchor
+ * holds, every entry is attacker-supplied, and there is no per-entry question
+ * to degrade to.
+ *
+ * SILENT SHORTENING IS THE RESIDUAL RISK, and the callback is the mitigation:
+ * a caller that ignores `onUnverifiableGrant` sees a shorter roster that
+ * looks complete. Treat a reported member as UNPROVEN — absence from the
+ * returned list means "no verified standing", which for authorization means
+ * deny, not "not in the vault".
+ *
+ * # `expectedVaultId` is the trust anchor, and it is why this is a
+ * # verification rather than a consistency check
+ *
+ * PASS THE ID YOU ASKED FOR — the same one handed to
+ * `sdk.memberships.signedRoster()`. It is required, and the requirement is
+ * the fix for the hole it closes:
+ *
+ * Every other value used here arrives INSIDE the response. Given only a
+ * roster, "verify it" can mean no more than "does this agree with itself?" —
+ * and it always does, because whoever composed it chose every field. Anyone
+ * able to answer on this address could sign a roster with a key of their own,
+ * name that key as `orgWalletPubkey`, and watch it verify.
+ *
+ * One externally-held value breaks the circle. `vaultIdFor` is a one-way
+ * derivation, so a key that derives `expectedVaultId` cannot be picked; it
+ * can only be the vault's actual owner. The two checks are therefore:
+ *
+ *   1. the roster must be FOR the vault asked about (`roster.vaultId`), which
+ *      is the binding the two separate calls otherwise leave open — a
+ *      response about somebody else's vault used to verify perfectly; and
+ *   2. `orgWalletPubkey` must DERIVE that vault, which pins the signing key
+ *      to an identity the response did not get to choose.
+ *
+ * Both run BEFORE any signature is checked, mirroring
+ * `RosterAuthority.verifyRoster` in ddc-node: until the anchor holds, every
+ * byte of the envelope is attacker-supplied, including the key the
+ * signatures would be checked against.
+ *
+ * A caller who holds the OWNER KEY rather than the id needs nothing extra —
+ * `vaultIdFor(ownerKey)` is the id. That direction works; the reverse does
+ * not exist.
+ *
+ * This anchors the roster to a vault, which is all a hash can do. It does not
+ * tell you the id itself is the vault you meant: if `expectedVaultId` was
+ * itself learned from an untrusted party, the result is trust in THAT party's
+ * choice of vault. Anchor it to something you already knew.
+ */
+export async function verifySignedRoster(roster, expectedVaultId, options = {}) {
+    if (typeof expectedVaultId !== "string" || expectedVaultId === "") {
+        throw new GrantVerificationError("expectedVaultId is required: verifying a roster against the vault id it " +
+            "carries only proves the response agrees with itself");
+    }
+    // The envelope is checked as SHAPE before anything is read out of it. A
+    // `grants: null` used to reach the `for` loop and surface as a bare
+    // TypeError — an error the caller cannot distinguish from a bug in their
+    // own code, on a path whose entire job is to report untrustworthy input.
+    if (typeof roster !== "object" || roster === null) {
+        throw new GrantVerificationError(`signed roster is not an object (got ${typeOf(roster)})`);
+    }
+    if (typeof roster.vaultId !== "string" || roster.vaultId === "") {
+        throw new GrantVerificationError("signed roster carries no vaultId");
+    }
+    if (typeof roster.orgWalletPubkey !== "string" || roster.orgWalletPubkey === "") {
+        throw new GrantVerificationError("signed roster carries no orgWalletPubkey");
+    }
+    if (!Array.isArray(roster.grants)) {
+        throw new GrantVerificationError(`signed roster's grants is not an array (got ${typeOf(roster.grants)})`);
+    }
+    // THE ANCHOR, both halves, before a single signature is checked.
+    if (roster.vaultId !== expectedVaultId) {
+        throw new GrantVerificationError(`signed roster names vault ${roster.vaultId}, asked about ${expectedVaultId}`);
+    }
+    if (vaultIdFor(roster.orgWalletPubkey) !== expectedVaultId) {
+        throw new GrantVerificationError(`orgWalletPubkey ${roster.orgWalletPubkey} does not derive vault ${expectedVaultId}`);
+    }
+    const out = [];
+    for (const grant of roster.grants) {
+        // A non-object entry is an ENTRY-level malformation — it belongs to no
+        // member in particular, but it is one row's bytes that are wrong, not the
+        // envelope's, so it degrades like any other unverifiable entry rather
+        // than poisoning the roster.
+        if (typeof grant !== "object" || grant === null) {
+            const err = new GrantVerificationError(`signed roster holds a grant that is not an object`);
+            options.onUnverifiableGrant?.(err);
+            continue;
+        }
+        try {
+            out.push(await verifyGrant(expectedVaultId, roster.orgWalletPubkey, grant));
+        }
+        catch (err) {
+            if (!(err instanceof GrantVerificationError))
+                throw err;
+            // DEGRADE THE ENTRY, NOT THE ROSTER — see the doc comment above for why
+            // this replaced the first-bad-entry throw, and what a caller owes the
+            // members reported here.
+            options.onUnverifiableGrant?.(err);
+        }
+    }
+    return out;
+}
+/** `typeof`, but naming `null` and arrays, for a message a caller can act on. */
+function typeOf(v) {
+    if (v === null)
+        return "null";
+    return Array.isArray(v) ? "an array" : typeof v;
+}
+/**
+ * One entry of `verifySignedRoster`, exposed for a caller holding a single
+ * grant (a member proving their own standing, say) rather than a whole
+ * roster. Same bindings, same fail-closed throw.
+ *
+ * `vaultId` and `orgWalletPubkey` must CORRESPOND — the same anchor
+ * `verifySignedRoster` applies, checked here too because both arguments are
+ * the caller's and the natural way to fill them is straight off a response,
+ * which is exactly the unanchored call this check refuses.
+ */
+export async function verifyGrant(vaultId, orgWalletPubkey, grant) {
+    if (vaultIdFor(orgWalletPubkey) !== vaultId) {
+        throw new GrantVerificationError(`orgWalletPubkey ${orgWalletPubkey} does not derive vault ${vaultId}`, grant.memberPubkey);
+    }
+    let doc;
+    try {
+        doc = decodeBase64(grant.doc);
+    }
+    catch (err) {
+        throw new GrantVerificationError(`grant document is not valid base64: ${err instanceof Error ? err.message : String(err)}`, grant.memberPubkey);
+    }
+    if (!(await verifyGrantSig(orgWalletPubkey, doc, grant.sig))) {
+        throw new GrantVerificationError(`grant document is not signed by the vault owner (${orgWalletPubkey})`, grant.memberPubkey);
+    }
+    let decoded;
+    try {
+        decoded = decodeGrantDoc(doc);
+    }
+    catch (err) {
+        throw new GrantVerificationError(err instanceof Error ? err.message : String(err), grant.memberPubkey);
+    }
+    if (decoded.vaultId !== vaultId || decoded.memberPubkey !== grant.memberPubkey) {
+        throw new GrantVerificationError(`grant document describes a different membership: it names ` +
+            `${decoded.memberPubkey} on ${decoded.vaultId}, and was served as ` +
+            `${grant.memberPubkey} on ${vaultId}`, grant.memberPubkey);
+    }
+    return decoded;
+}
+/**
+ * A required string field, or a typed failure naming it. With `absentOk`, an
+ * ABSENT key reads as `""` — for `privacyCeiling`, whose absence is v1's
+ * whole spelling and whose empty-string presence Go's decoder treats the
+ * same way. A present-but-non-string value still fails either way.
+ */
+function stringField(obj, key, absentOk = false) {
+    const v = obj[key];
+    if (v === undefined && absentOk)
+        return "";
+    if (typeof v !== "string") {
+        throw new Error(`decode grant: ${key} must be a string, got ${v === undefined ? "nothing" : typeof v}`);
+    }
+    return v;
+}
+/**
+ * `encoding/json`'s string encoding, which `JSON.stringify` does not
+ * reproduce: `<`, `>`, `&` and U+2028/U+2029 are escaped. Everything else is
+ * left to `JSON.stringify`, so the two agree on quotes, control characters
+ * and lone surrogates.
+ */
+function goString(s) {
+    return JSON.stringify(s)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+/**
+ * Sorts the way Go sorts strings — by UTF-8 bytes, which is code-point order.
+ * JavaScript's `<` compares UTF-16 code units and disagrees for astral
+ * characters, so `[...]sort()` would order a scope named "😀" (U+1F600)
+ * BEFORE one named "Ａ" (U+FF21) while Go puts it after, and the signature
+ * over the resulting bytes would never verify.
+ */
+function compareCodePoints(a, b) {
+    const ai = Array.from(a);
+    const bi = Array.from(b);
+    const n = Math.min(ai.length, bi.length);
+    for (let i = 0; i < n; i++) {
+        const x = ai[i].codePointAt(0);
+        const y = bi[i].codePointAt(0);
+        if (x !== y)
+            return x - y;
+    }
+    return ai.length - bi.length;
+}
+//# sourceMappingURL=grant-doc.js.map