@cef-ai/vault-sdk 3.3.0 → 4.0.0

package/dist/core/grant-doc.d.ts

@@ -0,0 +1,345 @@
+import type { SignedGrant, SignedRoster } from "./types.js";
+/**
+ * The schema string carried INSIDE the signed bytes (`authz.GrantSchema`).
+ *
+ * A v2 changes this string, so a v1 signature can never be replayed as a v2
+ * grant — which is why `decodeGrantDoc` refuses any other value instead of
+ * handing a v2 document's fields to a v1 reader under a signature that is
+ * perfectly valid for the v2 meaning.
+ */
+export declare const GRANT_SCHEMA = "cere.vault.grant.v1";
+/**
+ * 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 declare 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 declare 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 declare function canonicalPubkeyHex(s: string): string;
+/**
+ * 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 declare function vaultIdFor(walletPubkeyHex: string): string;
+/**
+ * A grant document's signed expiry: the moment the membership stops standing,
+ * as the opaque string its signer wrote — or {@link NO_GRANT_EXPIRY} when it
+ * never stops.
+ *
+ * A BRANDED string rather than a bare one, mirroring Go's `GrantExpiry`
+ * defined type and for exactly the same reason. `canonicalGrantBytes` takes
+ * `issuedAt` and `expiresAt` as its last two parameters; they are two
+ * timestamps of the same shape, side by side, so transposing them is the most
+ * likely slip at a call site — and with two plain `string`s that transposition
+ * COMPILES and signs valid bytes for the wrong document, a defect that
+ * presents as a key problem.
+ *
+ * Go gets that property from the scopes map for its other three strings; there
+ * is no such separator for this pair, so a distinct type is the whole defence
+ * on both sides. Use {@link grantExpiry} to make one.
+ */
+export type GrantExpiry = string & {
+    readonly __grantExpiry: unique symbol;
+};
+/**
+ * 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 declare const NO_GRANT_EXPIRY: GrantExpiry;
+/**
+ * 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 declare function grantExpiry(rfc3339: string): GrantExpiry;
+/**
+ * A canonical grant document, read back apart.
+ *
+ * `role` and `scopes`'s values are `string`, NOT `MemberRole` / `ScopeLevel`,
+ * and that is deliberate in both directions:
+ *
+ * - The signed document is the authority. A level this SDK version does not
+ *   know is a document this SDK should not silently rewrite or narrow — the
+ *   server passes it through unvalidated for the same reason. Refusing it is
+ *   the consumer's decision to make explicitly.
+ * - Go's `authz.Grant` is `Role string` / `Scopes map[string]string`. This is
+ *   its mirror, not a richer restatement of it.
+ */
+export interface Grant {
+    schema: string;
+    vaultId: string;
+    memberPubkey: string;
+    role: string;
+    scopes: Record<string, string>;
+    /**
+     * When the SIGNER minted this document, as the string it was signed as —
+     * by convention RFC3339 UTC, but UNPARSED here, so
+     * `canonicalGrantBytes(…, scopes, issuedAt)` reproduces the bytes exactly.
+     * Parse it yourself if you want the instant.
+     *
+     * Holding it is not permission to enforce on it. Nothing in this SDK or in
+     * vault-api checks an expiry against it, and a recent `issuedAt` on a
+     * PRESENTED document still says nothing about revocation — see the header.
+     */
+    issuedAt: string;
+    /**
+     * When the membership this document describes stops standing, as the string
+     * it was signed as — or `""` ({@link NO_GRANT_EXPIRY}) when it never does.
+     * Unparsed, like `issuedAt`, so re-encoding reproduces the bytes exactly.
+     *
+     * THIS IS A CLAIM, NOT AN ENFORCEMENT. Nothing here compares it to a clock.
+     * A roster you FETCHED already excludes expired memberships — vault-api
+     * filters them in SQL — which is the signal that actually carries expiry. On
+     * a document somebody HANDED you it is worth no more than `issuedAt` is:
+     * see the header's rule.
+     */
+    expiresAt: GrantExpiry;
+}
+/**
+ * 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.
+ *
+ * A THROWN error rather than a filtered-out entry, because every one of those
+ * states on an authorization artifact means the response is not what it
+ * claims to be. Silently dropping the bad entry and returning the rest would
+ * hand a caller a shorter roster that looks complete. `memberPubkey` names
+ * the entry so an operator can find it.
+ */
+export declare class GrantVerificationError extends Error {
+    /**
+     * 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.
+     */
+    readonly memberPubkey: string;
+    constructor(message: string, 
+    /**
+     * 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?: string);
+}
+/**
+ * The exact bytes a grant signature covers, mirroring
+ * `authz.CanonicalGrantBytes`.
+ *
+ * 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.
+ *
+ * `issuedAt` is LAST BUT ONE and `expiresAt` is LAST, mirroring Go's field and
+ * parameter order. In Go the map between `issuedAt` and the other strings is
+ * what makes a transposition a compile error instead of a valid signature over
+ * the wrong bytes; the one pair the map cannot sit between is `issuedAt` and
+ * `expiresAt`, which Go separates with a defined type and this file mirrors
+ * with {@link GrantExpiry}'s brand.
+ *
+ * `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.
+ */
+export declare function canonicalGrantBytes(vaultId: string, memberPubkey: string, role: string, scopes: Record<string, string>, issuedAt: string, expiresAt: GrantExpiry): Uint8Array;
+/**
+ * Reads a canonical grant document back into its parts, mirroring
+ * `authz.DecodeGrantDoc`. Never re-encodes; the bytes stay the authority.
+ *
+ * Throws on an unknown schema (see `GRANT_SCHEMA`) and on the same three
+ * required fields the encoder refuses to omit.
+ */
+export declare function decodeGrantDoc(doc: Uint8Array): Grant;
+/**
+ * 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 declare function verifyGrantSig(orgWalletPubkeyHex: string, doc: Uint8Array, sigHex: string): Promise<boolean>;
+/**
+ * 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 the 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.
+ *
+ * Fail-closed: the FIRST unverifiable entry throws
+ * `GrantVerificationError` and no partial list is returned. An authorization
+ * artifact with one entry you cannot prove is not a shorter roster, it is a
+ * roster you cannot trust.
+ *
+ * # `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 declare function verifySignedRoster(roster: SignedRoster, expectedVaultId: string): Promise<Grant[]>;
+/**
+ * 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 declare function verifyGrant(vaultId: string, orgWalletPubkey: string, grant: SignedGrant): Promise<Grant>;
+//# sourceMappingURL=grant-doc.d.ts.map

package/dist/core/grant-doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant-doc.d.ts","sourceRoot":"","sources":["../../src/core/grant-doc.ts"],"names":[],"mappings":"AA0FA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK5D;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAWpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,UAAU,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,aAAa,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAE7E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,EAAS,WAAW,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAExD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;;;;;;OASG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,SAAS,EAAE,WAAW,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM;gBAN7B,OAAO,EAAE,MAAM;IACf;;;;OAIG;IACM,YAAY,GAAE,MAAW;CAKrC;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,WAAW,GACrB,UAAU,CAsBZ;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,KAAK,CAsDrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,YAAY,EACpB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,KAAK,EAAE,CAAC,CA8ClB;AAQD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,KAAK,CAAC,CAwChB"}