@cef-ai/vault-sdk 3.3.0 → 4.0.0

package/dist/internal/memberships.d.ts

@@ -0,0 +1,360 @@
+import type { Signer } from "@cef-ai/signer";
+import type { VaultHttpClient } from "../core/http.js";
+import type { Member, MemberRole, MembershipSummary, ScopeGrants, SignedRoster } from "../core/types.js";
+/**
+ * What the caller already knows about the membership's OTHER half, so the
+ * grant document can be built without reading it back.
+ *
+ * The document always describes the membership as it will read AFTER the
+ * write, and each write route sets only one of its two components (see
+ * `Memberships`' doc comment). Absent, the SDK reads the other half from the
+ * server; supplied, it is signed as given — which saves the round trip for a
+ * console that already holds the roster, and is refused with a 400 naming the
+ * document the server derived if it is wrong.
+ */
+export interface PutMemberOptions {
+    /** The scope grants this member ALREADY holds. Default: read back. */
+    scopes?: ScopeGrants;
+}
+/** @see PutMemberOptions */
+export interface PutScopesOptions {
+    /**
+     * The standing this member ALREADY has — BOTH halves this route does not
+     * set. Default: read both back off the roster in one GET.
+     *
+     * ONE OPTION CARRYING TWO FIELDS, replacing the former `role?`. The grant
+     * document covers the role AND the expiry, and this route changes neither,
+     * so a caller who knew only the role would have had the SDK sign
+     * "never expires" for a membership that does expire — a document vault-api
+     * refuses, and would have honoured as a widening if it did not. Knowing
+     * half the standing is not knowing the standing.
+     *
+     * `expiresAt` absent inside this object means the membership has no expiry.
+     * Pass the spelling you read off `list()`; any spelling of the right
+     * instant is accepted, because the server compares instants (it cannot
+     * render the signer's original string back out of a timestamp column).
+     */
+    standing?: {
+        role: MemberRole;
+        expiresAt?: string;
+    };
+}
+/**
+ * Who belongs to a vault, in what role, holding which scope grants — and,
+ * from the other direction, which vaults the caller belongs to.
+ *
+ * ## THERE IS NO ORG ENTITY (D1)
+ *
+ * This class replaces `sdk.orgs`, which addressed an `orgId`. The `orgs`
+ * table and every `/api/v1/orgs…` route were removed, not aliased: a vault
+ * IS the organization, and **a vault BECOMES one by acquiring a second
+ * member**, which is `put()` below. There is deliberately no `create` — the
+ * removed `POST /api/v1/orgs` needed only half a replacement, the naming
+ * half, and that is `sdk.vault.rename()` (`PATCH /api/v1/vaults/:vaultId`),
+ * because a name is a property of the vault and a single-member vault must
+ * be nameable too.
+ *
+ * ## The one thing a consumer porting from `sdk.orgs` gets wrong
+ *
+ * `mine()` does NOT include the caller's own vault. `sdk.orgs.list()` folded
+ * the two together by synthesising an owner entry; the owner is never a
+ * membership row under D1, and `sdk.vault.current()` already answers "my own
+ * vault" keyed by wallet. **A switcher shows both by calling both** — and
+ * folding them here would double-count for anyone who did:
+ *
+ * ```ts
+ * const [own, joined] = await Promise.all([
+ *   sdk.vault.current(),        // the vault this wallet owns
+ *   sdk.memberships.mine(),     // the vaults this wallet was invited into
+ * ]);
+ * ```
+ *
+ * ## THE TWO WRITES CARRY A SECOND SIGNATURE, AND IT IS THE OWNER'S
+ *
+ * `put()` and `putScopes()` send `X-Grant-Signature`: the VAULT OWNER's
+ * ed25519 signature over the grant's canonical document
+ * (`canonicalGrantBytes`). ddc-node #1136 made it mandatory on both, so
+ * without it neither method can succeed at all — a 400 `grant sig: missing
+ * X-Grant-Signature`. They send `X-Grant-Issued-At` alongside it, carrying the
+ * moment the document was minted: it is inside the signed bytes, and the
+ * server rebuilds those bytes rather than receiving them, so it has no way to
+ * supply that field itself. It is a header of its own rather than the wallet auth's
+ * `X-Signature` because the two cover different bytes: `X-Signature` covers
+ * the request BODY and authenticates the caller, while this covers a document
+ * that names the vault, the member, the role and the scopes, so one signature
+ * cannot be replayed onto another member or another vault.
+ *
+ * `remove()` sends NO grant signature, and that is not an omission —
+ * `DeleteMember` has no such check. Read the handler before assuming
+ * symmetry: revocation deletes the row (and, by FK, its grants), so there is
+ * no post-write standing left for a document to describe.
+ *
+ * ### The document describes the membership AFTER the write, and each route
+ * ### knows only half of it
+ *
+ * `PutMember` builds its document from the role in the body and the scopes
+ * ALREADY IN THE STORE; `PutScopes` builds its own from the scopes in the
+ * body and the role already in the store. So each method reads the other half
+ * back before signing — one extra GET — unless the caller supplies it
+ * (`PutMemberOptions.scopes` / `PutScopesOptions.role`). Signing the same
+ * bytes for both calls is refused by the second.
+ *
+ * ### AN ADMIN WHO IS NOT THE OWNER CANNOT SIGN
+ *
+ * The route's gate admits the vault owner OR a live `role: "admin"` member,
+ * but `verifyGrantDocument` checks the signature against the VAULT's wallet
+ * key and nothing else. So an admin can be authorised to make this request
+ * and unable to produce the document it must carry. The SDK signs with the
+ * configured `signer`, which is the owner in the ordinary case of an owner
+ * administering their own vault; a non-owner admin gets a 400 naming the
+ * document, and needs one their owner signed out of band — pass it by calling
+ * the route through `VaultHttpClient` directly with the header set. There is
+ * no in-band way to obtain it today.
+ *
+ * ## Every mutation body carries a `timestamp`
+ *
+ * The wallet-signature middleware (`pkg/shared/auth/signature.go`) rejects
+ * ANY mutation body with no top-level RFC3339 `timestamp` as 401
+ * `INVALID_SIGNATURE "body missing timestamp"`, before the request reaches
+ * a handler. `WalletAuthProvider` supplies one during canonicalisation;
+ * `DelegationAuthProvider` (which never passes through that middleware)
+ * supplies nothing — so each method below sends its own, keeping the body
+ * correct on both paths. It is NOT a replay guard: ddc-node parses the field
+ * and no membership handler reads it.
+ */
+export declare class Memberships {
+    private readonly http;
+    private readonly signer?;
+    /**
+     * `signer` is the VAULT OWNER's key, and it is required by `put` and
+     * `putScopes` only — every read here, and `remove`, work without one.
+     * Optional so that constructing this class from
+     * `@cef-ai/vault-sdk/internal` for reads alone keeps working unchanged;
+     * a write without it throws `VaultSignerRequiredError` rather than
+     * sending a request the server will refuse.
+     */
+    constructor(http: VaultHttpClient, signer?: Signer | undefined);
+    /**
+     * The vaults the caller is a MEMBER of, with their own grants on each —
+     * the employee's vault switcher. `GET /api/v1/memberships`.
+     *
+     * Excludes the caller's own vault; see this class's doc comment, which is
+     * the single most likely thing to get wrong when porting from
+     * `sdk.orgs.list()`.
+     *
+     * LIVE memberships only: a membership that is suspended or past its
+     * `expiresAt` is absent, not present-with-a-state. `scopes` is always
+     * present on every entry (these are the caller's OWN grants, so there is
+     * no disclosure question) and is `{}` — never `null` — when they hold
+     * none.
+     */
+    mine(): Promise<MembershipSummary[]>;
+    /**
+     * The vault's roster. `GET /api/v1/vaults/:vaultId/members`.
+     *
+     * Readable by the vault owner or any of its own LIVE members, whatever
+     * their role; 403 (uniformly, so an outsider cannot enumerate) otherwise,
+     * and 404 if the vault was never claimed.
+     *
+     * THE OWNER ROW IS FIRST, is synthesised (`isOwner: true`, `role:
+     * "admin"`, `state: "active"`), and carries NO `scopes` — see `Member`.
+     * Every other row's `scopes` is present only when disclosed to the caller.
+     * `Member.scopes` being absent is NOT the same as `{}`; do not default it.
+     */
+    list(vaultId: string): Promise<Member[]>;
+    /**
+     * The same roster as SIGNED EVIDENCE.
+     * `GET /api/v1/vaults/:vaultId/roster/signed`.
+     *
+     * Each entry carries the canonical grant document the vault owner signed
+     * and that signature, so a party that does NOT trust this vault-api can
+     * decide what a member may do. That is the entire point of the route, and
+     * it only holds if the consumer checks the documents AGAINST SOMETHING
+     * THIS RESPONSE DID NOT SUPPLY:
+     *
+     * ```ts
+     * import { verifySignedRoster } from "@cef-ai/vault-sdk";
+     *
+     * const roster = await sdk.memberships.signedRoster(vaultId);
+     * const grants = await verifySignedRoster(roster, vaultId);  // throws on any entry
+     * // act on `grants` — never on roster.grants[i].role / .scopes
+     * ```
+     *
+     * **Pass the SAME `vaultId` you asked for.** `verifySignedRoster` requires
+     * it and will not verify without it, because the alternative is not a
+     * weaker check but a meaningless one: `orgWalletPubkey` arrives inside the
+     * response, so a roster checked only against itself proves that whoever
+     * answered can sign — never that they are the vault's owner. The id is the
+     * one value the responder does not get to choose; `vaultIdFor` makes the
+     * owner key answer to it. A caller holding the owner key instead of the id
+     * gets the id from `vaultIdFor(ownerKey)`.
+     *
+     * What this does NOT establish: that the vault id is the one you meant. It
+     * anchors the roster to a vault, so anchor the vault to something you knew
+     * beforehand rather than to a value the same untrusted party handed you.
+     *
+     * The raw shape is returned rather than the verified one so evidence can be
+     * forwarded to a third party intact; `verifySignedRoster` is the step that
+     * turns it into values worth acting on. `SignedGrant.role` and
+     * `.scopes` are vault-api's own decoding of `doc`, provided for display —
+     * enforcing on them verifies one thing and enforces another.
+     *
+     * Same gate and same disclosure rule as `list()`: readable by the owner or
+     * any LIVE member (404 for an unclaimed vault, a uniform 403 otherwise),
+     * owner and live admin see every grant, a plain member only their own. Two
+     * differences from `list()`, both deliberate: the owner is NOT an entry
+     * here (they hold no signed document — `orgWalletPubkey` is where they
+     * appear), and only LIVE memberships are served, so there is no `state`
+     * field to check.
+     */
+    signedRoster(vaultId: string): Promise<SignedRoster>;
+    /**
+     * Adds or updates a member. `PUT /api/v1/vaults/:vaultId/members/:memberPubkey`.
+     *
+     * **This is how a vault becomes an organization** — there is no
+     * registration step; the first successful call is the whole ceremony.
+     *
+     * Requires the vault owner or a live `role: "admin"` member. 400 if
+     * `memberPubkey` is the vault's own owner — the owner is never a
+     * membership row (D1) — and 404 if the vault is unclaimed.
+     *
+     * `memberPubkey` should already be in the server's canonical
+     * 0x-lowercase-hex spelling (`auth.CanonicalPubKeyHex`), which is the one
+     * spelling every authorization read looks members up by.
+     *
+     * `expiresAt` MUST BE RFC 3339 — vault-api parses it for the timestamptz
+     * column and 400s anything else, naming the field. It is also INSIDE THE
+     * SIGNED DOCUMENT now, and the server rebuilds the document from the string
+     * this method sends: the exact spelling passed here is what is signed and
+     * what is sent, never re-derived from a `Date` on either side. Formatting it
+     * twice is how the two copies drift by a trimmed fractional zero and the
+     * signature fails as though the key were wrong.
+     *
+     * The returned `Member` carries neither `scopes` nor `isOwner`: it is the
+     * row just written, and grants are a separate call (`putScopes`).
+     *
+     * CARRIES THE OWNER'S `X-Grant-Signature` over
+     * `{vaultId, memberPubkey, role, scopes, issuedAt, expiresAt}` — see the
+     * class doc comment. The scopes in that document are the ones the member
+     * ALREADY HOLDS, because this route sets the role only, so re-roling a
+     * member with grants signs those grants too. They are read back with `scopes()` (a 404 — the new
+     * member case — is `{}`); pass `{ scopes }` to skip that GET when they are
+     * already in hand.
+     */
+    put(vaultId: string, memberPubkey: string, role: MemberRole, expiresAt?: string, opts?: PutMemberOptions): Promise<Member>;
+    /**
+     * Removes a member row. `DELETE /api/v1/vaults/:vaultId/members/:memberPubkey`.
+     *
+     * 409 — not 404 — for the vault's own owner: they cannot be removed at
+     * all, and 404 would read as "already gone, nothing left to do" to an
+     * admin who believed they had locked the founder out.
+     *
+     * ddc-node's handler never reads the body, but the wallet-signature
+     * middleware still requires a top-level `timestamp` on every mutation
+     * regardless of what the handler does with it — so this body is
+     * `{timestamp}` and nothing else.
+     *
+     * NO `X-Grant-Signature`, deliberately and after reading `DeleteMember`:
+     * the grant check lives in `verifyGrantDocument`, which only `PutMember`
+     * and `PutScopes` call. Adding one here on the assumption that the three
+     * writes are symmetrical would send a header the server ignores and would
+     * make this method need a signer it has no use for.
+     */
+    remove(vaultId: string, memberPubkey: string): Promise<void>;
+    /**
+     * A member's scope grants.
+     * `GET /api/v1/vaults/:vaultId/members/:memberPubkey/scopes`.
+     *
+     * Readable by the vault owner, a live admin, or the member themselves.
+     * 404 when the membership does not exist — INCLUDING when the vault OWNER
+     * asks for their own grants, which is the read-side face of "the owner is
+     * never a row": their authority is key math and there is no grant row.
+     *
+     * `list()` already carries `scopes` inline on every disclosed row, so a
+     * console rendering a roster should NOT call this per member — that is an
+     * N+1. This is for reading one membership's grants directly.
+     */
+    scopes(vaultId: string, memberPubkey: string): Promise<{
+        scopes: ScopeGrants;
+    }>;
+    /**
+     * Replaces a member's FULL scope-grant set.
+     * `PUT /api/v1/vaults/:vaultId/members/:memberPubkey/scopes`.
+     *
+     * The server deletes then reinserts, so this is never a merge or a diff
+     * against the existing grants — send the complete intended set. 404 if the
+     * membership row does not exist, INCLUDING for an empty `scopes` map: the
+     * check is EXISTENCE, not liveness, so an admin may prepare the grants of
+     * a currently-suspended membership.
+     *
+     * CARRIES THE OWNER'S `X-Grant-Signature` over
+     * `{vaultId, memberPubkey, role, scopes, issuedAt, expiresAt}` — see the
+     * class doc comment. The role AND the expiry in that document are the ones
+     * the member ALREADY HOLDS, because this route sets the scopes only; both
+     * are read off the roster (`list()`) in one GET, which is why a
+     * `memberPubkey` with no row fails here rather than as the server's 404.
+     * Pass `{ standing: { role, expiresAt } }` to skip it.
+     *
+     * THE EXPIRY IS ALSO SENT IN THE BODY, and that is the one place this route
+     * differs from `put`. vault-api holds the expiry as a timestamp and the
+     * document carries the signer's STRING, which a timestamp cannot be
+     * rendered back into — so the server cannot supply this field the way it
+     * supplies the role. It checks what is sent against the stored instant, so
+     * stating it cannot widen the membership: a different moment is a 400.
+     */
+    putScopes(vaultId: string, memberPubkey: string, scopes: ScopeGrants, opts?: PutScopesOptions): Promise<void>;
+    /**
+     * The vault owner's signature over this grant's canonical document, as the
+     * `X-Grant-Signature` header — see the class doc comment for why a write
+     * cannot land without it.
+     *
+     * `memberPubkey` is canonicalised FIRST. The server canonicalises the URL
+     * parameter before it derives the bytes (`memberPubkeyParam`), so signing
+     * the caller's own spelling of a bare or upper-case key produces a valid
+     * signature over a document the server never builds — a 400 that reads as
+     * a key problem. `vaultId` is NOT canonicalised, because the server does
+     * not touch it either.
+     *
+     * ED25519 ONLY, and checked here. `authz.VerifyGrantSig` hard-codes
+     * `SchemeEd25519` (unlike the request-auth middleware, which also takes
+     * sr25519), so an sr25519 owner can authenticate the request and still
+     * never produce a document the server will accept. Named up front rather
+     * than left to surface as an opaque signature refusal.
+     */
+    private grantHeader;
+    /**
+     * The scope grants this member holds RIGHT NOW — the half of `put`'s
+     * document that route reads from the store rather than from its body.
+     *
+     * A 404 is `{}`, not a failure: it is what `GET .../scopes` answers for a
+     * membership row that does not exist yet, which is the ordinary case of
+     * adding a NEW member, and it is exactly what the server's own
+     * `ListScopeGrantsForMember` yields there (it tolerates `ErrNotFound`).
+     * Every other error propagates — a 403 means this caller may not administer
+     * the vault at all, and guessing `{}` would turn it into a puzzling 400
+     * from the write instead.
+     */
+    private heldScopes;
+    /**
+     * The role AND expiry this member holds RIGHT NOW — the two halves of
+     * `putScopes`'s document that route reads from the store rather than from
+     * its body.
+     *
+     * BOTH OUT OF ONE ROW, deliberately. They used to be one value read here
+     * and one value the document did not carry at all; now that the expiry is
+     * signed, fetching them separately would be two chances for them to
+     * describe different moments of the same membership.
+     *
+     * From the roster rather than from a route of its own, because there is no
+     * single-membership read that carries a role: `GET .../scopes` returns only
+     * grants. The synthesised OWNER row is skipped explicitly — the owner is
+     * never a membership row (D1), so a `memberPubkey` matching it is the
+     * server's 400, not a standing to sign.
+     *
+     * `expiresAt` absent on the row means the membership does not expire; the
+     * roster omits the key rather than sending null (Go `omitempty`), which is
+     * the same three-state distinction `Member.scopes` documents.
+     */
+    private heldStanding;
+}
+//# sourceMappingURL=memberships.d.ts.map

package/dist/internal/memberships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memberships.d.ts","sourceRoot":"","sources":["../../src/internal/memberships.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAavD,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,YAAY,EACb,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,4BAA4B;AAC5B,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AACH,qBAAa,WAAW;IAUpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAV1B;;;;;;;OAOG;gBAEgB,IAAI,EAAE,eAAe,EACrB,MAAM,CAAC,EAAE,MAAM,YAAA;IAGlC;;;;;;;;;;;;;OAaG;IACH,IAAI,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAIpC;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,GAAG,CACP,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,MAAM,CAAC;IAalB;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5D;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,WAAW,CAAA;KAAE,CAAC;IAI/E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,SAAS,CACb,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC;IAUhB;;;;;;;;;;;;;;;;;OAiBG;YACW,WAAW;IAiDzB;;;;;;;;;;;OAWG;YACW,UAAU;IASxB;;;;;;;;;;;;;;;;;;;OAmBG;YACW,YAAY;CAkB3B"}