@gemmein/sdk 0.4.7 → 0.5.0

package/REFERENCE.md

@@ -21,10 +21,15 @@ The browser client. `appKey` is your public `pk_...` key. `options` (optional):
 
 ### `gemmeinServer(secretKey, options?) → GemmeinServer`
 Server-only client for a `sk_...` secret key — **never ship this to the
-browser.** Exposes read/update on collections without a signed-in user,
+browser.** `options` (optional): `{ apiUrl?: string }` — **the option is
+`apiUrl`**, not `baseUrl`. An unknown option is ignored silently, so a script
+that passes `baseUrl` to reach a local or staging server quietly talks to
+production instead. Exposes read/update on collections without a signed-in user,
 `notify()` to email one of your app's own verified people (see **Notify**),
-plus `testSession()` for CI self-tests (dev environments only — see
-**Reaffirm**).
+the gate — `verifySession()` / `holdings()` / `grantAccess()` /
+`revokeAccess()`, for code of yours running on your own host (see **Server
+gate**) — plus `testSession()` for CI self-tests (dev environments only —
+see **Reaffirm**).
 
 The client has two layers. **Your app's collections** — `g.collection(name)`
 (the canonical spelling; `g.storage.collection(name)` is the same client). And
@@ -233,6 +238,10 @@ Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
 don't also redirect to the returned `url`, and never build a Stripe URL
 yourself. Gate features on `(await g.subscriptions.mine())?.plan === "pro"`;
 gate one-off fulfilment on the receipt record, never the redirect.
+By-hand grants (trial, promotion, a support comp) are not listed to the
+app — a gated read simply succeeds — so never rebuild the paywall from
+`mine()`; let the server refuse with `entitlement_required`. The two grant
+families and what ends each are in llms.txt, "Two FAMILIES of grant".
 
 ---
 
@@ -262,6 +271,88 @@ honestly, not hidden.)
 
 ---
 
+## Server gate — `gemmeinServer(sk).verifySession` / `holdings` / `grantAccess` / `revokeAccess`
+
+Gemmein hosts no compute. **Your own** function — Vercel, a VPS, a cron box,
+anywhere — asks Gemmein the only three questions it has: *who is this person,
+what do they hold, change what they hold.*
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `verifySession` | `(token)` | `Promise<{ ok: true, person: { id, email, role }, holdings: Holdings }>` — the browser's session token in, identity **and** holdings out. Needs no capability on the key (the caller already holds the person's token) and never touches the session: no extension, no last-seen |
+| `holdings` | `(personId)` | `Promise<{ ok: true, person: { id, email, role, suspended }, holdings: Holdings }>` — for the paths with no token in hand. A **suspended** person is returned, flagged `suspended: true`, with their holdings; `verifySession` refuses them |
+| `grantAccess` | `(personId, { entitlement, source?, expiresAt?, reason? })` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` (201) — `holdings` is the state **after**; the owner's audit row carries before→after and the key's name |
+| `revokeAccess` | `(personId, grantId, { reason? }?)` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` — the returned grant carries `revokedAt` |
+
+```ts
+type Holdings = {
+  access: string[]                 // the keys they hold NOW — ["access:pro"]
+  grants: Grant[]                  // the LIVE grants behind them (revoked/expired are gone)
+  credits: { balance: number } | null   // reserved — null today; credits are NOT shipped
+}
+
+type Grant = {
+  id: string
+  entitlement: string              // "access:<slug>" — the plan's or product's own key
+  source: "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration"
+  startsAt: string
+  expiresAt: string | null
+  revokedAt?: string | null        // present on the grant revokeAccess returns
+}
+```
+
+- **Pointing at a non-default server.** `gemmeinServer(sk, { apiUrl })` — the option
+  is **`apiUrl`**. `baseUrl` is not an option name and is ignored in silence, so a
+  test or E2E script that passes it runs against **production** without saying so.
+- **One call per request.** `verifySession` answers identity *and* holdings
+  together — don't call it twice, and don't cache the answer past the request.
+- **Holdings, not billing.** The gate never returns subscription status,
+  amounts, Stripe ids, or a grant's `sourceId` — the source **kind** only. Gate
+  on what a person *holds*, never on what they pay. Person id, never an email.
+- **Two capabilities, ticked by the human.** `verifySession` needs neither.
+  `holdings` needs **"Look up a person's access by id"**; `grantAccess` and
+  `revokeAccess` need **"Grant and revoke access"** — plain-English checkboxes
+  the owner ticks when minting the key. Existing keys have both off, so nothing
+  in production changes.
+- **Manual sources only.** `source` ∈ `manual | trial | promotion | migration`
+  (default `manual`). Purchases and subscriptions come only from Stripe — a key
+  cannot mint paid access. A key *may* end a payment-made grant (the same as the
+  dashboard's "end this access"); the payment itself is untouched.
+- **One grant, one reason.** `reason` (≤ 200 chars) is what the owner reads in
+  their logs and is never edited. `sourceId` is minted per call, so two calls
+  make two grants — call it once and keep your own retry key.
+- **Nothing silent, within a stated bound.** Every `/server/*` call a **resolved
+  secret key** makes, ok or refused, lands in that key's usage ledger — the owner
+  reads the summary on their Keys page and the full day × route × outcome table in
+  the key's own room. A rejected or publishable (`pk_`) key can't be attributed to a
+  key row, so its refusal reaches only the request log. Refusals also write one audit
+  row per key, route and code each hour (exact counts stay in the ledger); grants and
+  revokes write full before→after rows, attributed to the key by name. A refusal
+  counts as *use*: "last used" means last seen, not last worked. In `gemmein dev` the
+  local key already holds both capabilities, and the usage read is cloud-only — the
+  local runtime never mounts the console.
+
+| code | status | meaning · do |
+|------|--------|--------------|
+| `session_invalid` | 401 | No session matches this token — send the person to sign in again; never store or reuse tokens across people |
+| `session_expired` | 401 | The session ended (the message names when) — send them back to sign-in |
+| `session_revoked` | 401 | A newer sign-in, a sign-out, or the owner ended it — send them back to sign-in |
+| `person_suspended` | 403 | The owner suspended this person — access is off until the owner reactivates them in the dashboard |
+| `person_not_found` | 404 | No person with this id in this app and environment — ids come from `verifySession` or the dashboard, never from an email. Existence is never leaked |
+| `capability_required` | 403 | The key's box isn't ticked — mint a key with "Look up a person's access by id" / "Grant and revoke access" ticked (purchases still come only from Stripe) |
+| `invalid_source` | 400 | `purchase` / `subscription` asked for by hand — refused; those come only from Stripe |
+| `invalid_entitlement` | 400 | Not a valid `access:<slug>` key — or drop the key and pass the plan's or product's own NAME, which the gate resolves for you |
+| `unknown_plan` | 400 | No plan or product by that name — the owner adds it on the Payments page. (Checkout's `unknown_plan` is a **404**; the gate's is a **400** — it is a bad argument to a write, not a missing resource) |
+| `grant_not_found` | 404 | Not this person's grant, in this app and environment — re-read `holdings` |
+| `already_revoked` | 409 | A grant ends once (`revokedAt` is set and never edited) — it is already ended |
+| `invalid_body` | 400 | One malformed field, whichever it is — `token` (missing, not a string, over 512 chars), `expiresAt` (unparseable or in the past), `reason` (not text, over 200 chars). Branch on the code, read the **message**: it names the field |
+| `scope_denied` | 403 | Not a secret key — the gate is server-only, never the browser |
+| `invalid_id` | 400 | A prototype name (`__proto__`, `constructor`, `prototype`) was sent as a person id or a grant id. Ids come from `verifySession()` or the dashboard — never from a name |
+| `unknown_route` | 404 | Not one of the gate's four routes — the message lists them all |
+| `method_not_allowed` | 405 | The right route, the wrong verb: `verifySession`, `grantAccess` and `revokeAccess` are POST, `holdings` is GET |
+
+---
+
 ## Reaffirm — prove your app's boundaries in CI
 
 Gemmein enforces the rules **server-side**, so your frontend is never the source
@@ -329,7 +420,10 @@ class GemmeinError extends Error {
 }
 ```
 
-Branch on `err.code`. The stable codes:
+Branch on `err.code`. The gate's own codes (`session_invalid`,
+`session_expired`, `session_revoked`, `person_suspended`, `person_not_found`,
+`capability_required`, `invalid_source`, `unknown_plan`, `grant_not_found`,
+`already_revoked`) are in **Server gate** above, each with its action. The rest:
 
 | code | meaning | do |
 |------|---------|-----|

package/dist/index.cjs

@@ -816,6 +816,126 @@ class GemmeinServer {
         }
         return response.json();
     }
+    /**
+     * THE GATE — your compute, our answer. Gemmein runs no code of yours;
+     * your own function runs anywhere and asks the only three questions it
+     * has: who is this person, what do they hold, change what they hold.
+     *
+     *   const { person, holdings } = await g.verifySession(token);
+     *   if (!holdings.access.includes("access:pro")) return deny();
+     *
+     * ONE call per request answers identity AND holdings — don't call it
+     * twice, and don't cache the answer past the request. Verify needs no
+     * capability on the key (the caller already holds the person's token)
+     * and never touches the session: no extension, no last-seen.
+     *
+     * Refusals (`err.code`): `session_invalid` (no session matches this
+     * token — the person signs in again; never reuse tokens across
+     * people) · `session_expired` · `session_revoked` (a newer sign-in,
+     * a sign-out, or the owner) — all three send the person back to
+     * sign-in · `person_suspended` (the owner suspended them; access is
+     * off until the owner reactivates them in the dashboard) ·
+     * `invalid_body` (token missing, not a string, or over 512 chars).
+     */
+    async verifySession(token) {
+        return this.gate("/server/verify-session", {
+            method: "POST",
+            body: JSON.stringify({ token }),
+        });
+    }
+    /**
+     * What one of YOUR people holds, by person id — for the paths where no
+     * token is in hand (a webhook of your own, a nightly job, an admin
+     * screen you built). A person id, NEVER an email address: ids come
+     * from `verifySession` or the dashboard.
+     *
+     * A suspended person is RETURNED, with `suspended: true`, alongside
+     * their holdings — your function may need to say so. The gate itself
+     * (`verifySession`) refuses them.
+     *
+     * Refusals: `capability_required` — this key can't look up people by
+     * id; ask your human to mint a key with "Look up a person's access by
+     * id" ticked, or use `verifySession` with the person's own token ·
+     * `person_not_found` (404 — no person with this id in this app and
+     * environment; existence is never leaked).
+     */
+    async holdings(personId) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/holdings`);
+    }
+    /**
+     * Give a person access by hand — a trial, a promotion, an apology, a
+     * migration from your old system:
+     *
+     *   await g.grantAccess(personId, {
+     *     entitlement: "access:pro",     // or the plan's NAME, e.g. "Pro"
+     *     source: "trial",
+     *     expiresAt: "2026-10-01T00:00:00.000Z",
+     *     reason: "7-day trial from the onboarding flow",
+     *   });
+     *
+     * MANUAL sources only. Purchases and subscriptions come only from
+     * Stripe — a key cannot mint paid access, by design. `reason` is up to
+     * 200 characters, is never edited afterwards, and is what the owner
+     * reads in their logs; write it for them.
+     *
+     * `sourceId` is minted per call, so two calls make TWO grants (each
+     * with its own one reason) — call it once, and keep your own retry
+     * key if the caller can retry.
+     *
+     * Returns the new grant and the holdings AFTER it; the owner's audit
+     * row carries before→after and the key's name.
+     *
+     * Refusals: `capability_required` — this key can't grant access; ask
+     * your human to mint a key with "Grant and revoke access" ticked ·
+     * `invalid_source` (purchase/subscription refused) ·
+     * `invalid_entitlement` / `unknown_plan` (no plan or product by that
+     * name — the owner adds it on the Payments page) · `person_not_found`.
+     */
+    async grantAccess(personId, input) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/grants`, {
+            method: "POST",
+            body: JSON.stringify({
+                entitlement: input.entitlement,
+                ...(input.source ? { source: input.source } : {}),
+                ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+                ...(input.reason ? { reason: input.reason } : {}),
+            }),
+        });
+    }
+    /**
+     * End one grant — the reversibility law in one call:
+     *
+     *   await g.revokeAccess(personId, grant.id, { reason: "trial ended" });
+     *
+     * A grant ends ONCE: `revokedAt` is set and never edited, so a second
+     * call is `409 already_revoked`, not a silent no-op. A key MAY end a
+     * grant that a payment created (the same as the owner's "end this
+     * access" button) — the payment itself is untouched, and the audit row
+     * says so.
+     *
+     * Returns the revoked grant and the holdings after it.
+     *
+     * Refusals: `capability_required` (same ticked box as granting) ·
+     * `grant_not_found` (404 — not this person's grant, in this app and
+     * environment; existence is never leaked) · `already_revoked` (409).
+     */
+    async revokeAccess(personId, grantId, input = {}) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/grants/${encodeURIComponent(grantId)}/revoke`, { method: "POST", body: JSON.stringify({ ...(input.reason ? { reason: input.reason } : {}) }) });
+    }
+    // One request path for the four gate calls, so every refusal reaches
+    // the caller through the SAME typed error the rest of the SDK throws —
+    // `err.code` carries the server's own code, `err.message` its sentence
+    // (which always names the next action).
+    async gate(path, init = {}) {
+        const headers = { "x-app-key": this.secretKey };
+        if (init.body)
+            headers["content-type"] = "application/json";
+        const response = await fetch(new URL(path, this.apiUrl), { ...init, headers });
+        if (!response.ok) {
+            throw new GemmeinError({ status: response.status, ...(await readErrorBody(response)) });
+        }
+        return response.json();
+    }
 }
 exports.GemmeinServer = GemmeinServer;
 class ServerCollectionClient {

package/dist/index.d.cts

@@ -525,6 +525,46 @@ export type GemmeinServerOptions = {
     secretKey: string;
     apiUrl?: string;
 };
+/**
+ * Where a grant came from — the KIND only. The gate never returns the
+ * source's id, an amount, or anything from Stripe.
+ */
+export type GrantSource = "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration";
+/**
+ * The sources a secret key may create by hand. `purchase` and
+ * `subscription` are deliberately absent: money-made access comes only
+ * from Stripe, and always will.
+ */
+export type ManualGrantSource = "manual" | "trial" | "promotion" | "migration";
+export type Grant = {
+    id: string;
+    /** `access:<slug>` — the plan's or product's own key. */
+    entitlement: string;
+    source: GrantSource;
+    startsAt: string;
+    expiresAt: string | null;
+    /** Present on the grant returned by `revokeAccess` — set once, never edited. */
+    revokedAt?: string | null;
+};
+/**
+ * What a person holds RIGHT NOW — never what they pay. `access` is the
+ * union of live grants' keys; `grants` lists those live grants (revoked
+ * and expired ones are gone, not flagged). `credits` is a reserved slot:
+ * it is `null` today because consumable credits are not shipped — don't
+ * design around them until this type says otherwise.
+ */
+export type Holdings = {
+    access: string[];
+    grants: Grant[];
+    credits: {
+        balance: number;
+    } | null;
+};
+export type GatePerson = {
+    id: string;
+    email: string;
+    role: string;
+};
 export declare class GemmeinServer {
     private readonly apiUrl;
     private readonly secretKey;
@@ -582,6 +622,119 @@ export declare class GemmeinServer {
         replyRail?: boolean;
         recorded?: boolean;
     }>;
+    /**
+     * THE GATE — your compute, our answer. Gemmein runs no code of yours;
+     * your own function runs anywhere and asks the only three questions it
+     * has: who is this person, what do they hold, change what they hold.
+     *
+     *   const { person, holdings } = await g.verifySession(token);
+     *   if (!holdings.access.includes("access:pro")) return deny();
+     *
+     * ONE call per request answers identity AND holdings — don't call it
+     * twice, and don't cache the answer past the request. Verify needs no
+     * capability on the key (the caller already holds the person's token)
+     * and never touches the session: no extension, no last-seen.
+     *
+     * Refusals (`err.code`): `session_invalid` (no session matches this
+     * token — the person signs in again; never reuse tokens across
+     * people) · `session_expired` · `session_revoked` (a newer sign-in,
+     * a sign-out, or the owner) — all three send the person back to
+     * sign-in · `person_suspended` (the owner suspended them; access is
+     * off until the owner reactivates them in the dashboard) ·
+     * `invalid_body` (token missing, not a string, or over 512 chars).
+     */
+    verifySession(token: string): Promise<{
+        ok: true;
+        person: GatePerson;
+        holdings: Holdings;
+    }>;
+    /**
+     * What one of YOUR people holds, by person id — for the paths where no
+     * token is in hand (a webhook of your own, a nightly job, an admin
+     * screen you built). A person id, NEVER an email address: ids come
+     * from `verifySession` or the dashboard.
+     *
+     * A suspended person is RETURNED, with `suspended: true`, alongside
+     * their holdings — your function may need to say so. The gate itself
+     * (`verifySession`) refuses them.
+     *
+     * Refusals: `capability_required` — this key can't look up people by
+     * id; ask your human to mint a key with "Look up a person's access by
+     * id" ticked, or use `verifySession` with the person's own token ·
+     * `person_not_found` (404 — no person with this id in this app and
+     * environment; existence is never leaked).
+     */
+    holdings(personId: string): Promise<{
+        ok: true;
+        person: GatePerson & {
+            suspended: boolean;
+        };
+        holdings: Holdings;
+    }>;
+    /**
+     * Give a person access by hand — a trial, a promotion, an apology, a
+     * migration from your old system:
+     *
+     *   await g.grantAccess(personId, {
+     *     entitlement: "access:pro",     // or the plan's NAME, e.g. "Pro"
+     *     source: "trial",
+     *     expiresAt: "2026-10-01T00:00:00.000Z",
+     *     reason: "7-day trial from the onboarding flow",
+     *   });
+     *
+     * MANUAL sources only. Purchases and subscriptions come only from
+     * Stripe — a key cannot mint paid access, by design. `reason` is up to
+     * 200 characters, is never edited afterwards, and is what the owner
+     * reads in their logs; write it for them.
+     *
+     * `sourceId` is minted per call, so two calls make TWO grants (each
+     * with its own one reason) — call it once, and keep your own retry
+     * key if the caller can retry.
+     *
+     * Returns the new grant and the holdings AFTER it; the owner's audit
+     * row carries before→after and the key's name.
+     *
+     * Refusals: `capability_required` — this key can't grant access; ask
+     * your human to mint a key with "Grant and revoke access" ticked ·
+     * `invalid_source` (purchase/subscription refused) ·
+     * `invalid_entitlement` / `unknown_plan` (no plan or product by that
+     * name — the owner adds it on the Payments page) · `person_not_found`.
+     */
+    grantAccess(personId: string, input: {
+        entitlement: string;
+        source?: ManualGrantSource;
+        expiresAt?: string;
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        grant: Grant;
+        holdings: Holdings;
+    }>;
+    /**
+     * End one grant — the reversibility law in one call:
+     *
+     *   await g.revokeAccess(personId, grant.id, { reason: "trial ended" });
+     *
+     * A grant ends ONCE: `revokedAt` is set and never edited, so a second
+     * call is `409 already_revoked`, not a silent no-op. A key MAY end a
+     * grant that a payment created (the same as the owner's "end this
+     * access" button) — the payment itself is untouched, and the audit row
+     * says so.
+     *
+     * Returns the revoked grant and the holdings after it.
+     *
+     * Refusals: `capability_required` (same ticked box as granting) ·
+     * `grant_not_found` (404 — not this person's grant, in this app and
+     * environment; existence is never leaked) · `already_revoked` (409).
+     */
+    revokeAccess(personId: string, grantId: string, input?: {
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        grant: Grant;
+        holdings: Holdings;
+    }>;
+    private gate;
 }
 declare class ServerCollectionClient {
     private readonly apiUrl;

package/dist/index.d.ts

@@ -525,6 +525,46 @@ export type GemmeinServerOptions = {
     secretKey: string;
     apiUrl?: string;
 };
+/**
+ * Where a grant came from — the KIND only. The gate never returns the
+ * source's id, an amount, or anything from Stripe.
+ */
+export type GrantSource = "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration";
+/**
+ * The sources a secret key may create by hand. `purchase` and
+ * `subscription` are deliberately absent: money-made access comes only
+ * from Stripe, and always will.
+ */
+export type ManualGrantSource = "manual" | "trial" | "promotion" | "migration";
+export type Grant = {
+    id: string;
+    /** `access:<slug>` — the plan's or product's own key. */
+    entitlement: string;
+    source: GrantSource;
+    startsAt: string;
+    expiresAt: string | null;
+    /** Present on the grant returned by `revokeAccess` — set once, never edited. */
+    revokedAt?: string | null;
+};
+/**
+ * What a person holds RIGHT NOW — never what they pay. `access` is the
+ * union of live grants' keys; `grants` lists those live grants (revoked
+ * and expired ones are gone, not flagged). `credits` is a reserved slot:
+ * it is `null` today because consumable credits are not shipped — don't
+ * design around them until this type says otherwise.
+ */
+export type Holdings = {
+    access: string[];
+    grants: Grant[];
+    credits: {
+        balance: number;
+    } | null;
+};
+export type GatePerson = {
+    id: string;
+    email: string;
+    role: string;
+};
 export declare class GemmeinServer {
     private readonly apiUrl;
     private readonly secretKey;
@@ -582,6 +622,119 @@ export declare class GemmeinServer {
         replyRail?: boolean;
         recorded?: boolean;
     }>;
+    /**
+     * THE GATE — your compute, our answer. Gemmein runs no code of yours;
+     * your own function runs anywhere and asks the only three questions it
+     * has: who is this person, what do they hold, change what they hold.
+     *
+     *   const { person, holdings } = await g.verifySession(token);
+     *   if (!holdings.access.includes("access:pro")) return deny();
+     *
+     * ONE call per request answers identity AND holdings — don't call it
+     * twice, and don't cache the answer past the request. Verify needs no
+     * capability on the key (the caller already holds the person's token)
+     * and never touches the session: no extension, no last-seen.
+     *
+     * Refusals (`err.code`): `session_invalid` (no session matches this
+     * token — the person signs in again; never reuse tokens across
+     * people) · `session_expired` · `session_revoked` (a newer sign-in,
+     * a sign-out, or the owner) — all three send the person back to
+     * sign-in · `person_suspended` (the owner suspended them; access is
+     * off until the owner reactivates them in the dashboard) ·
+     * `invalid_body` (token missing, not a string, or over 512 chars).
+     */
+    verifySession(token: string): Promise<{
+        ok: true;
+        person: GatePerson;
+        holdings: Holdings;
+    }>;
+    /**
+     * What one of YOUR people holds, by person id — for the paths where no
+     * token is in hand (a webhook of your own, a nightly job, an admin
+     * screen you built). A person id, NEVER an email address: ids come
+     * from `verifySession` or the dashboard.
+     *
+     * A suspended person is RETURNED, with `suspended: true`, alongside
+     * their holdings — your function may need to say so. The gate itself
+     * (`verifySession`) refuses them.
+     *
+     * Refusals: `capability_required` — this key can't look up people by
+     * id; ask your human to mint a key with "Look up a person's access by
+     * id" ticked, or use `verifySession` with the person's own token ·
+     * `person_not_found` (404 — no person with this id in this app and
+     * environment; existence is never leaked).
+     */
+    holdings(personId: string): Promise<{
+        ok: true;
+        person: GatePerson & {
+            suspended: boolean;
+        };
+        holdings: Holdings;
+    }>;
+    /**
+     * Give a person access by hand — a trial, a promotion, an apology, a
+     * migration from your old system:
+     *
+     *   await g.grantAccess(personId, {
+     *     entitlement: "access:pro",     // or the plan's NAME, e.g. "Pro"
+     *     source: "trial",
+     *     expiresAt: "2026-10-01T00:00:00.000Z",
+     *     reason: "7-day trial from the onboarding flow",
+     *   });
+     *
+     * MANUAL sources only. Purchases and subscriptions come only from
+     * Stripe — a key cannot mint paid access, by design. `reason` is up to
+     * 200 characters, is never edited afterwards, and is what the owner
+     * reads in their logs; write it for them.
+     *
+     * `sourceId` is minted per call, so two calls make TWO grants (each
+     * with its own one reason) — call it once, and keep your own retry
+     * key if the caller can retry.
+     *
+     * Returns the new grant and the holdings AFTER it; the owner's audit
+     * row carries before→after and the key's name.
+     *
+     * Refusals: `capability_required` — this key can't grant access; ask
+     * your human to mint a key with "Grant and revoke access" ticked ·
+     * `invalid_source` (purchase/subscription refused) ·
+     * `invalid_entitlement` / `unknown_plan` (no plan or product by that
+     * name — the owner adds it on the Payments page) · `person_not_found`.
+     */
+    grantAccess(personId: string, input: {
+        entitlement: string;
+        source?: ManualGrantSource;
+        expiresAt?: string;
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        grant: Grant;
+        holdings: Holdings;
+    }>;
+    /**
+     * End one grant — the reversibility law in one call:
+     *
+     *   await g.revokeAccess(personId, grant.id, { reason: "trial ended" });
+     *
+     * A grant ends ONCE: `revokedAt` is set and never edited, so a second
+     * call is `409 already_revoked`, not a silent no-op. A key MAY end a
+     * grant that a payment created (the same as the owner's "end this
+     * access" button) — the payment itself is untouched, and the audit row
+     * says so.
+     *
+     * Returns the revoked grant and the holdings after it.
+     *
+     * Refusals: `capability_required` (same ticked box as granting) ·
+     * `grant_not_found` (404 — not this person's grant, in this app and
+     * environment; existence is never leaked) · `already_revoked` (409).
+     */
+    revokeAccess(personId: string, grantId: string, input?: {
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        grant: Grant;
+        holdings: Holdings;
+    }>;
+    private gate;
 }
 declare class ServerCollectionClient {
     private readonly apiUrl;

package/dist/index.js

@@ -799,6 +799,126 @@ export class GemmeinServer {
         }
         return response.json();
     }
+    /**
+     * THE GATE — your compute, our answer. Gemmein runs no code of yours;
+     * your own function runs anywhere and asks the only three questions it
+     * has: who is this person, what do they hold, change what they hold.
+     *
+     *   const { person, holdings } = await g.verifySession(token);
+     *   if (!holdings.access.includes("access:pro")) return deny();
+     *
+     * ONE call per request answers identity AND holdings — don't call it
+     * twice, and don't cache the answer past the request. Verify needs no
+     * capability on the key (the caller already holds the person's token)
+     * and never touches the session: no extension, no last-seen.
+     *
+     * Refusals (`err.code`): `session_invalid` (no session matches this
+     * token — the person signs in again; never reuse tokens across
+     * people) · `session_expired` · `session_revoked` (a newer sign-in,
+     * a sign-out, or the owner) — all three send the person back to
+     * sign-in · `person_suspended` (the owner suspended them; access is
+     * off until the owner reactivates them in the dashboard) ·
+     * `invalid_body` (token missing, not a string, or over 512 chars).
+     */
+    async verifySession(token) {
+        return this.gate("/server/verify-session", {
+            method: "POST",
+            body: JSON.stringify({ token }),
+        });
+    }
+    /**
+     * What one of YOUR people holds, by person id — for the paths where no
+     * token is in hand (a webhook of your own, a nightly job, an admin
+     * screen you built). A person id, NEVER an email address: ids come
+     * from `verifySession` or the dashboard.
+     *
+     * A suspended person is RETURNED, with `suspended: true`, alongside
+     * their holdings — your function may need to say so. The gate itself
+     * (`verifySession`) refuses them.
+     *
+     * Refusals: `capability_required` — this key can't look up people by
+     * id; ask your human to mint a key with "Look up a person's access by
+     * id" ticked, or use `verifySession` with the person's own token ·
+     * `person_not_found` (404 — no person with this id in this app and
+     * environment; existence is never leaked).
+     */
+    async holdings(personId) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/holdings`);
+    }
+    /**
+     * Give a person access by hand — a trial, a promotion, an apology, a
+     * migration from your old system:
+     *
+     *   await g.grantAccess(personId, {
+     *     entitlement: "access:pro",     // or the plan's NAME, e.g. "Pro"
+     *     source: "trial",
+     *     expiresAt: "2026-10-01T00:00:00.000Z",
+     *     reason: "7-day trial from the onboarding flow",
+     *   });
+     *
+     * MANUAL sources only. Purchases and subscriptions come only from
+     * Stripe — a key cannot mint paid access, by design. `reason` is up to
+     * 200 characters, is never edited afterwards, and is what the owner
+     * reads in their logs; write it for them.
+     *
+     * `sourceId` is minted per call, so two calls make TWO grants (each
+     * with its own one reason) — call it once, and keep your own retry
+     * key if the caller can retry.
+     *
+     * Returns the new grant and the holdings AFTER it; the owner's audit
+     * row carries before→after and the key's name.
+     *
+     * Refusals: `capability_required` — this key can't grant access; ask
+     * your human to mint a key with "Grant and revoke access" ticked ·
+     * `invalid_source` (purchase/subscription refused) ·
+     * `invalid_entitlement` / `unknown_plan` (no plan or product by that
+     * name — the owner adds it on the Payments page) · `person_not_found`.
+     */
+    async grantAccess(personId, input) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/grants`, {
+            method: "POST",
+            body: JSON.stringify({
+                entitlement: input.entitlement,
+                ...(input.source ? { source: input.source } : {}),
+                ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+                ...(input.reason ? { reason: input.reason } : {}),
+            }),
+        });
+    }
+    /**
+     * End one grant — the reversibility law in one call:
+     *
+     *   await g.revokeAccess(personId, grant.id, { reason: "trial ended" });
+     *
+     * A grant ends ONCE: `revokedAt` is set and never edited, so a second
+     * call is `409 already_revoked`, not a silent no-op. A key MAY end a
+     * grant that a payment created (the same as the owner's "end this
+     * access" button) — the payment itself is untouched, and the audit row
+     * says so.
+     *
+     * Returns the revoked grant and the holdings after it.
+     *
+     * Refusals: `capability_required` (same ticked box as granting) ·
+     * `grant_not_found` (404 — not this person's grant, in this app and
+     * environment; existence is never leaked) · `already_revoked` (409).
+     */
+    async revokeAccess(personId, grantId, input = {}) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/grants/${encodeURIComponent(grantId)}/revoke`, { method: "POST", body: JSON.stringify({ ...(input.reason ? { reason: input.reason } : {}) }) });
+    }
+    // One request path for the four gate calls, so every refusal reaches
+    // the caller through the SAME typed error the rest of the SDK throws —
+    // `err.code` carries the server's own code, `err.message` its sentence
+    // (which always names the next action).
+    async gate(path, init = {}) {
+        const headers = { "x-app-key": this.secretKey };
+        if (init.body)
+            headers["content-type"] = "application/json";
+        const response = await fetch(new URL(path, this.apiUrl), { ...init, headers });
+        if (!response.ok) {
+            throw new GemmeinError({ status: response.status, ...(await readErrorBody(response)) });
+        }
+        return response.json();
+    }
 }
 class ServerCollectionClient {
     constructor(apiUrl, secretKey, name) {

package/llms.txt

@@ -49,9 +49,14 @@ creating no accounts is the correct behavior until the verdict is in.
      nothing in between — so an app whose CORE loop needs teams, roles
      or seats DOESN'T FIT
    - carts, quantities, physical goods, shipping, inventory
-   - credits, usage metering, seats (paid access is yes-or-no)
-   - hosted functions or cron: Gemmein runs no code of yours — but read
-     the server-side note closing this section before counting that a gap
+   - credits or usage metering TODAY (paid access is yes-or-no; consumable
+     credits are planned, not shipped — don't design around them yet, and
+     never sell a "credit pack" until this file says the ledger exists)
+   - seats (owner-run: not coming)
+   - hosted functions or cron: Gemmein runs no code of yours — but your
+     own function anywhere asks Gemmein who a person is and what they
+     hold; read the server-side note closing this section before
+     counting that a gap
    - custody of money (Stripe holds all funds; your human brings or
      creates their own Stripe account when the app charges)
    - multi-seller payouts or revenue splits: every payment lands whole in
@@ -74,8 +79,10 @@ code on your human's OWN host — Vercel, a VPS, anywhere — holding a
 secret key already reads and updates collections and sends event emails
 with `notify()`. (A secret key sees PAST the safety rules — every
 customer's records — which is why it never touches a browser. It cannot
-create or delete records, verify a session, or read one customer's
-plan: those are the signed-in customer's own calls, or the dashboard's.)
+create or delete records: those are the signed-in customer's own calls,
+or the dashboard's. It CAN verify a session token and read what that
+person holds — the gate — and, when your human ticks the box on the key,
+look a person up by id and grant or revoke access by hand.)
 "This app needs a server-side piece" is therefore not a gap by itself:
 the verdict downgrades when the server piece needs a call a secret key
 cannot make, or when the app needs compute your human has nowhere to
@@ -345,6 +352,62 @@ contents.
   cap (a security notice never loses to five order emails); misusing it
   for campaigns shows in your own audit trail. In `gemmein dev` the send
   prints in the terminal (NOTIFY · …) instead of mailing.
+- Your compute, our gate: when code of yours must run elsewhere (a model
+  call, a PDF render, a nightly job), Gemmein hosts none of it — your own
+  function runs anywhere and asks Gemmein its only three questions: who is
+  this person, what do they hold, change what they hold.
+
+      import { gemmeinServer } from "@gemmein/sdk";
+      const g = gemmeinServer(process.env.GEMMEIN_SECRET_KEY);
+      const { person, holdings } = await g.verifySession(token);
+      if (!holdings.access.includes("access:pro")) return deny();
+      await g.holdings(personId);                    // no token in hand
+      await g.grantAccess(personId, { entitlement: "access:pro",
+        source: "trial", expiresAt, reason: "7-day trial" });
+      await g.revokeAccess(personId, grantId, { reason: "trial ended" });
+
+  ONE verifySession per request answers identity AND holdings — don't
+  call it twice, don't cache the answer past the request. `holdings` is
+  what the person holds NOW: `access` (keys like "access:pro"), `grants`
+  (each with its source KIND only — subscription | purchase | manual |
+  trial | promotion | migration — plus start and expiry), and `credits`,
+  a reserved slot that is always `null` today (consumable credits are NOT
+  shipped; don't design around them). Never subscription status, amounts
+  or Stripe ids: gate on what a person HOLDS, never on billing. Person
+  id, NEVER an email address. verifySession needs nothing extra; looking
+  someone up by id and granting are new power, so they sit behind per-key
+  checkboxes the HUMAN ticks when minting the key — ask your human to
+  tick "Look up a person's access by id" / "Grant and revoke access". A
+  key grants MANUAL access only (manual | trial | promotion | migration):
+  purchases and subscriptions still come only from Stripe. Every /server/*
+  call a resolved secret key makes, ok or refused, lands in that key's
+  usage ledger on the owner's Keys page (a rejected or publishable key
+  can't be attributed, so it reaches only the request log); refusals also
+  write one activity row per key, route and code each hour. In `gemmein
+  dev` the local key already holds both capabilities, and the usage read
+  is cloud-only — the local runtime never mounts the console. The
+  refusals, and what to do:
+      session_invalid     no session matches this token — the person must
+                          sign in again; never reuse tokens across people
+      session_expired     the session ended — back to sign-in
+      session_revoked     newer sign-in, sign-out, or the owner — sign-in
+      person_suspended    the owner suspended them — access is off until
+                          the owner reactivates them in the dashboard
+      person_not_found    no person with this id in this app and env —
+                          ids come from verifySession or the dashboard
+      capability_required the box isn't ticked on this key — ask your
+                          human to mint one with it ticked
+      unknown_plan        no plan or product by that name — the owner
+                          adds it on the Payments page
+      grant_not_found     not this person's grant here — re-read holdings
+      already_revoked     a grant ends once — it is already ended
+      invalid_source      purchase/subscription asked for by hand — use
+                          manual | trial | promotion | migration instead
+      invalid_id          a prototype name (__proto__, constructor) was
+                          sent as a person or grant id — ids come from
+                          verifySession or the dashboard, never a name
+      invalid_body        one malformed field (token, expiresAt, reason)
+                          — the message names which one and what it needs
 - Linking records (author on a post, product on an order): store the other
   record's id in a field (`authorProfileId: profile.id`) — in collections
   users write (community, shared, direct) the server learns it's a link;
@@ -509,7 +572,40 @@ contents.
   screen and send them to checkout; retry only after they hold one. Proof surfaces: `await g.purchases.mine()`
   (everything they paid for, refunds applied, with the `grants` each purchase
   carries) and `await g.subscriptions.mine()`.
-  NO credits, NO usage limits, NO seats — access is yes-or-no by design.
+  NO credits or usage limits YET — access is yes-or-no today. Consumable
+  credits (buy a pack, spend atomically, a zero floor) are planned, not
+  shipped: until this file teaches them, a "100 credit pack" is NOT a
+  pattern (the webhook can only SET a number, so a second pack erases the
+  first). NO seats, by design — not coming.
+- Two FAMILIES of grant, and the line between them is law. Every grant is
+  one key + one reason + a start + maybe an end, never edited (an extension
+  is a NEW grant). PURCHASE-TIED (`subscription`, `purchase`): written only
+  by Stripe's signed webhook when money arrives — never by the owner's
+  hand, never by your app; a subscription grant ends on cancellation or
+  lapse, a purchase grant on a FULL refund (partial leaves it); the only
+  grants that count as revenue. Revoking one by hand stops the access and
+  refunds nothing. BY-HAND (`manual`, `trial`, `promotion`, plus
+  `migration` for customers imported from elsewhere): the owner writes them
+  from a customer's page — plan or product BY NAME, optional end date, a
+  reason — and they end on that date or when revoked; never revenue; a
+  refund never touches them. Effective access is the union of both
+  families. WHEN A REFUND MEETS ACCESS, THE OWNER DECIDES: the platform
+  revokes only on events that plainly mean it (subscription cancelled or
+  lapsed; one-off purchase refunded IN FULL). A partial refund leaves
+  access; a refund on a subscription invoice touches no access at all
+  (grants are revoked by purchase reference, subscriptions by customer).
+  A cancel-at-period-end keeps access until the period ends. If the owner
+  wants access gone NOW, they cancel the subscription immediately in
+  Stripe or revoke by hand on the customer's page — both audited; every
+  refund the webhook chose not to act on is written to the activity view.
+  Tell your human this when they ask "I refunded them, why can they still
+  get in" — never write refund logic in the app. Your app sees purchases (`g.purchases.mine()`, each with its
+  `grants`) and the subscription (`g.subscriptions.mine()`) — by-hand
+  grants are NOT listed to the app; a gated read simply succeeds. So never
+  rebuild the paywall client-side from what you can list: let the server
+  refuse and show the upgrade prompt on `entitlement_required`. "Give X a
+  free month" is a trial grant on their customer page, never code — ask
+  your human.
 - Selling THINGS (one-off purchases — a beat, an ebook, a course; DIGITAL
   access only — physical goods, shipping, inventory and carts are out of
   scope, said out loud): plans are for subscriptions; products are for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "Gemmein SDK — passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
   "license": "MIT",
   "type": "module",