@foir/sdk 0.19.0 → 0.21.0

package/dist/react.js

@@ -14,6 +14,26 @@ import {
 // src/graphql/foir-request.ts
 import { print as print2 } from "graphql";
 
+// src/transport/key-kind.ts
+var KEY_PREFIXES = [
+  ["foir_pub_", "publishable"],
+  ["foir_srv_", "server"],
+  ["foir_adm_", "admin"],
+  ["pk_", "publishable"],
+  ["sk_", "older"],
+  ["tc_", "older"]
+];
+function foirKeyKind(apiKey) {
+  if (typeof apiKey !== "string") return void 0;
+  for (const [prefix, kind] of KEY_PREFIXES) {
+    if (apiKey.startsWith(prefix)) return kind;
+  }
+  return void 0;
+}
+function isPublishableFoirKey(apiKey) {
+  return foirKeyKind(apiKey) === "publishable";
+}
+
 // src/graphql/cdn-route.ts
 import { print } from "graphql";
 
@@ -117,6 +137,28 @@ function refuseCredentialHeaders(extra) {
   }
 }
 var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
+function sentCoordinate(value) {
+  return Math.round(value * 100) / 100;
+}
+async function resolveFoirVisitor(source) {
+  const value = typeof source === "function" ? await source() : source;
+  if (value === null || value === void 0) return { place: {} };
+  if (typeof value === "string") {
+    const address2 = value.trim();
+    return { address: address2 || void 0, place: {} };
+  }
+  const address = value.address?.trim();
+  const country = value.country?.trim();
+  const place = {};
+  if (country) place.country = country;
+  if (Number.isFinite(value.latitude) && Number.isFinite(value.longitude)) {
+    place.location = {
+      latitude: sentCoordinate(value.latitude),
+      longitude: sentCoordinate(value.longitude)
+    };
+  }
+  return { address: address || void 0, place };
+}
 function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json"
@@ -560,7 +602,7 @@ function toVariableValue(value, label) {
     return value.toISOString();
   }
   if (Array.isArray(value)) {
-    return value.filter((item) => item !== void 0).map((item, index) => toVariableValue(item, `${label}[${index}]`));
+    return value.filter((item) => item !== void 0).map((item, index2) => toVariableValue(item, `${label}[${index2}]`));
   }
   if (kind === "object") {
     const out = {};
@@ -733,10 +775,7 @@ function foirDataEndpoint(apiUrl, path) {
   return foirApiEndpoint(apiUrl, path);
 }
 async function resolveVisitorAddress(config) {
-  const source = config.visitor;
-  const value = typeof source === "function" ? await source() : source;
-  const address = value?.trim();
-  return address ? address : void 0;
+  return (await resolveFoirVisitor(config.visitor)).address;
 }
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
@@ -777,7 +816,7 @@ async function resolveFoirAuth(config) {
   };
 }
 function foirRoute(input) {
-  if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
+  if (!isPublishableFoirKey(input.apiKey)) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
   if (input.orgId || input.orgUrl) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
@@ -915,6 +954,9 @@ var AUTH_OPS = {
   // Post-credential self reads.
   currentUser: "currentUser",
   myProviderToken: "myProviderToken",
+  // What the calling credential may do, and for a signed-in customer the roles
+  // they hold. `./access` reads it.
+  whoami: "whoami",
   // Methods.
   customerLogin: "customerLogin",
   customerRegister: "customerRegister",
@@ -1078,6 +1120,280 @@ async function refreshSession(adapter, env) {
     return null;
   }
 }
+function isAuthExpiredError(err) {
+  if (!(err instanceof FoirRequestError)) return false;
+  if (err.status === 401) return true;
+  return (err.graphQLErrors ?? []).some(
+    (e) => /authentication required/i.test(e.message)
+  );
+}
+var refreshing = /* @__PURE__ */ new WeakMap();
+function refreshSessionOnce(adapter, env) {
+  const running = refreshing.get(adapter);
+  if (running) return running;
+  const next = refreshSession(adapter, env).finally(() => refreshing.delete(adapter));
+  refreshing.set(adapter, next);
+  return next;
+}
+function sessionLapse(err) {
+  if (err instanceof FoirAuthDowngradedError) {
+    switch (err.downgrade.reason) {
+      case "expired":
+        return "refresh";
+      case "invalid":
+        return "expired";
+      default:
+        return null;
+    }
+  }
+  return isAuthExpiredError(err) ? "refresh" : null;
+}
+async function withSessionRefresh(adapter, env, run) {
+  const token = await getSessionToken(adapter);
+  try {
+    return await run(token ?? void 0);
+  } catch (err) {
+    const lapse = sessionLapse(err);
+    if (!lapse) throw err;
+    if (lapse === "expired") throw new FoirSessionExpiredError({ cause: err });
+    const refreshed = await refreshSessionOnce(adapter, env);
+    if (!refreshed) {
+      if (err instanceof FoirAuthDowngradedError) throw new FoirSessionExpiredError({ cause: err });
+      throw err;
+    }
+    try {
+      return await run(refreshed.token);
+    } catch (again) {
+      if (again instanceof FoirAuthDowngradedError) throw new FoirSessionExpiredError({ cause: again });
+      throw again;
+    }
+  }
+}
+async function authedOp(adapter, env, op, args) {
+  return withSessionRefresh(
+    adapter,
+    env,
+    (bearerToken) => authOp(env, op, args, { bearerToken })
+  );
+}
+
+// src/auth/grant-table.generated.ts
+var GRANT_TABLE = [
+  ["records:read", true, ["own", "all"], []],
+  ["records:create", true, [], []],
+  ["records:write", true, ["own", "all"], []],
+  ["records:delete", true, ["own", "all"], []],
+  ["records:publish", true, ["own", "all"], []],
+  ["records:attribute", true, [], []],
+  ["search:read", true, [], []],
+  ["embeddings:read", false, [], []],
+  ["embeddings:write", false, [], []],
+  ["schemas:read", false, [], []],
+  ["drafts:read", false, [], []],
+  ["files:read", false, ["own", "all"], []],
+  ["files:write", false, ["own", "all"], []],
+  ["files:delete", false, ["own", "all"], []],
+  ["notifications:read", false, ["own", "all"], []],
+  ["notifications:write", false, ["own", "named", "all"], []],
+  ["notifications:consent", false, [], []],
+  ["pushcredentials:read", false, [], []],
+  ["pushcredentials:write", false, [], []],
+  ["notes:read", false, ["own", "all"], []],
+  ["notes:write", false, ["own", "all"], []],
+  ["notes:create", false, [], []],
+  ["approvals:read", false, [], []],
+  ["approvals:write", false, [], []],
+  ["rooms:read", true, [], []],
+  ["rooms:write", true, [], []],
+  ["presence:read", true, [], []],
+  ["operations:read", false, [], []],
+  ["operations:execute", true, [], []],
+  ["operations:write", false, [], []],
+  ["operations:complete", false, [], []],
+  ["status:write", false, [], []],
+  ["appconfig:read", false, [], []],
+  ["schedules:read", false, [], []],
+  ["schedules:write", false, [], []],
+  ["hooks:read", false, [], []],
+  ["hooks:write", false, [], []],
+  ["relyingparties:read", false, [], []],
+  ["relyingparties:write", false, [], []],
+  ["domains:read", false, [], []],
+  ["domains:write", false, [], []],
+  ["secrets:read", false, [], []],
+  ["secrets:list", false, [], []],
+  ["secrets:put", false, [], []],
+  ["secrets:delete", false, [], []],
+  ["appsecrets:read", false, [], []],
+  ["appsecrets:list", false, [], []],
+  ["appsecrets:put", false, [], []],
+  ["appsecrets:delete", false, [], []],
+  ["opsecrets:read", false, [], []],
+  ["opsecrets:write", false, [], []],
+  ["settings:read", false, [], []],
+  ["settings:write", false, [], []],
+  ["designtokens:read", false, [], []],
+  ["designtokens:write", false, [], []],
+  ["models:read", false, [], []],
+  ["models:write", false, [], []],
+  ["configs:read", false, [], []],
+  ["configs:write", false, [], []],
+  ["apps:read", false, [], []],
+  ["apps:write", false, [], []],
+  ["events:read", false, [], []],
+  ["targeting:debug", false, [], []],
+  ["visitors:forward", false, [], []],
+  ["apikeys:read", false, [], []],
+  ["apikeys:write", false, [], []],
+  ["organizations:read", false, [], []],
+  ["organizations:write", false, [], []],
+  ["organizations:create", false, [], []],
+  ["organizations:delete", false, [], []],
+  ["organizations:reach", false, [], []],
+  ["members:read", false, [], []],
+  ["members:write", false, [], []],
+  ["roles:read", false, [], []],
+  ["roles:write", false, [], []],
+  ["projects:read", false, [], []],
+  ["projects:write", false, [], []],
+  ["project:manage", false, [], ["records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "auth:login_with_foir", "relyingparties:read", "relyingparties:write", "domains:read", "domains:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
+  ["projects:create", false, [], []],
+  ["projects:delete", false, [], []],
+  ["tenants:read", false, [], []],
+  ["tenants:write", false, [], []],
+  ["tenants:delete", false, [], []],
+  ["audit:read", false, [], []],
+  ["export:run", false, [], []],
+  ["billing:read", false, [], []],
+  ["billing:manage", false, [], []],
+  ["usage:read", false, [], []],
+  ["controlkeys:read", false, [], []],
+  ["controlkeys:write", false, [], []],
+  ["tenanthooks:read", false, [], []],
+  ["tenanthooks:write", false, [], []],
+  ["apps:install", false, [], []],
+  ["tenant:manage", false, [], ["project:manage", "projects:create", "projects:delete", "tenants:read", "tenants:write", "tenants:delete", "export:run", "billing:read", "billing:manage", "usage:read", "controlkeys:read", "controlkeys:write", "tenanthooks:read", "tenanthooks:write", "apps:install"]],
+  ["platform:read", false, [], []],
+  ["platform:manage", false, [], ["tenant:manage", "platform:read", "platform:create_workspace", "users:setup"]],
+  ["platform:create_workspace", false, [], []],
+  ["users:read", false, ["own", "named", "all"], []],
+  ["users:write", false, ["own", "all"], []],
+  ["users:setup", false, [], []],
+  ["users:delete", false, ["own", "all"], []],
+  ["users:create", false, [], []],
+  ["identities:read", false, [], []],
+  ["identities:delete", false, [], []],
+  ["usersecrets:read", false, [], []],
+  ["usersecrets:list", false, [], []],
+  ["usersecrets:put", false, [], []],
+  ["usersecrets:delete", false, [], []],
+  ["auth:login_with_foir", false, [], []],
+  ["signinproviders:read", false, [], []],
+  ["signinproviders:write", false, [], []]
+];
+
+// src/auth/grants.ts
+var WILDCARD = "*";
+var RESOURCE_WILDCARD = ":*";
+var index;
+function catalogue() {
+  if (!index) {
+    const byName = new Map(GRANT_TABLE.map((row) => [row[0], row]));
+    const longestFirst = [...byName.keys()].sort(
+      (a, b) => a.length !== b.length ? b.length - a.length : a < b ? -1 : 1
+    );
+    index = { byName, longestFirst };
+  }
+  return index;
+}
+var reachRank = { own: 1, named: 2, all: 3 };
+function hasReach(permission, reach) {
+  const reaches = permission[2];
+  return reaches.length === 0 ? reach === "own" : reaches.includes(reach);
+}
+function resourceOf(name) {
+  const i = name.indexOf(":");
+  return i < 0 ? name : name.slice(0, i);
+}
+function parseGrant(s) {
+  const { byName, longestFirst } = catalogue();
+  for (const name of longestFirst) {
+    if (!s.startsWith(name)) continue;
+    let rest = s.slice(name.length);
+    if (rest !== "" && rest[0] !== "." && rest[0] !== ":") continue;
+    const permission = byName.get(name);
+    let reach = "own";
+    if (rest.startsWith(".")) {
+      const after = rest.slice(1);
+      const colon = after.indexOf(":");
+      const word = colon < 0 ? after : after.slice(0, colon);
+      if (word !== "named" && word !== "all") return null;
+      if (!hasReach(permission, word)) return null;
+      reach = word;
+      rest = after.slice(word.length);
+    }
+    let target = "";
+    if (rest.startsWith(":")) {
+      target = rest.slice(1);
+      if (!permission[1]) return null;
+      if (target === "" || /[: \t\n*]/.test(target)) return null;
+    }
+    return { permission, reach, target };
+  }
+  return null;
+}
+function covers(held, required) {
+  return held.permission === required.permission && reachRank[held.reach] >= reachRank[required.reach] && (held.target === "" || held.target === required.target);
+}
+function resourceWildcard(held) {
+  if (!held.endsWith(RESOURCE_WILDCARD)) return null;
+  const resource = held.slice(0, -RESOURCE_WILDCARD.length);
+  return resource.includes(":") ? null : resource;
+}
+function holdsAt(held, required, depth) {
+  for (const h of held) {
+    if (h === WILDCARD) return true;
+    const resource = resourceWildcard(h);
+    if (resource !== null) {
+      if (resource === resourceOf(required.permission[0])) return true;
+      continue;
+    }
+    const grant = parseGrant(h);
+    if (grant === null) continue;
+    if (covers(grant, required)) return true;
+    const implies = grant.permission[3];
+    if (depth < 4 && implies.length > 0 && holdsAt(implies, required, depth + 1)) return true;
+  }
+  return false;
+}
+function holds(held, required) {
+  const grant = parseGrant(required);
+  return grant !== null && holdsAt(held, grant, 0);
+}
+
+// src/auth/access.ts
+function accessFrom(who) {
+  const customer = who?.credential?.customer;
+  if (!customer?.id) return null;
+  return {
+    customerId: customer.id,
+    roles: Array.isArray(customer.roles) ? [...customer.roles] : null,
+    scopes: [...who?.authority?.effective ?? []]
+  };
+}
+async function customerAccess(env, options) {
+  return accessFrom(await authOp(env, AUTH_OPS.whoami, void 0, options));
+}
+async function getSessionAccess(adapter, env) {
+  if (!await getSessionToken(adapter)) return null;
+  return accessFrom(await authedOp(adapter, env, AUTH_OPS.whoami));
+}
+function hasRole(access, key) {
+  return access?.roles?.includes(key) ?? false;
+}
+function hasScope(access, scope) {
+  return access ? holds(access.scopes, scope) : false;
+}
 
 // src/auth/session-client.ts
 var DEFAULT_SESSION_PATH = "/session/token";
@@ -1254,9 +1570,16 @@ function FoirProvider({
   if (adapter && adapter !== adapterRef.current) adapterRef.current = adapter;
   const [status, setStatus] = useState("loading");
   const [customer, setCustomer] = useState(null);
+  const [access, setAccess] = useState(null);
+  const [accessStatus, setAccessStatus] = useState("idle");
+  const accessRead = useRef(0);
+  const accessPending = useRef(null);
   const apply = useCallback((c) => {
     setCustomer(c);
     setStatus(c ? "authenticated" : "unauthenticated");
+    accessRead.current += 1;
+    setAccess(null);
+    setAccessStatus("idle");
   }, []);
   const loginOrigin = hostedSession?.loginOrigin;
   const sessionPath = hostedSession?.sessionPath;
@@ -1381,6 +1704,39 @@ function FoirProvider({
     () => hosted ? hosted.getToken() : getSessionToken(adapterRef.current),
     [hosted]
   );
+  const loadAccess = useCallback(() => {
+    const read = accessRead.current += 1;
+    setAccessStatus((was) => was === "ready" ? was : "loading");
+    const pending = (async () => {
+      try {
+        const next = hosted ? await hosted.getToken().then(
+          (bearerToken) => bearerToken ? customerAccess(envRef.current, { bearerToken }) : null
+        ) : await getSessionAccess(adapterRef.current, envRef.current);
+        if (accessRead.current !== read) return;
+        setAccess(next);
+        setAccessStatus("ready");
+      } catch {
+        if (accessRead.current !== read) return;
+        setAccess(null);
+        setAccessStatus("unavailable");
+      }
+    })();
+    accessPending.current = pending;
+    void pending.finally(() => {
+      if (accessPending.current === pending) accessPending.current = null;
+    });
+    return pending;
+  }, [hosted]);
+  const ensureAccess = useCallback(
+    () => accessPending.current ?? loadAccess(),
+    [loadAccess]
+  );
+  const accessWasRead = accessStatus !== "idle";
+  const refreshWithAccess = useCallback(async () => {
+    const ok = await refresh();
+    if (ok && accessWasRead) await loadAccess();
+    return ok;
+  }, [refresh, loadAccess, accessWasRead]);
   const getProviders = useCallback(() => getAuthProviders(envRef.current), []);
   const hostedSignInUrl = useMemo(
     () => hosted ? (returnTo) => hosted.signInUrl(returnTo) : null,
@@ -1390,6 +1746,10 @@ function FoirProvider({
     () => ({
       status,
       customer,
+      access,
+      accessStatus,
+      loadAccess,
+      ensureAccess,
       env,
       adapter: adapterRef.current,
       signIn,
@@ -1399,7 +1759,7 @@ function FoirProvider({
       signInWithProvider,
       completeProviderLogin,
       signOut: signOut2,
-      refresh,
+      refresh: refreshWithAccess,
       getToken,
       getProviders,
       hostedSignInUrl
@@ -1407,6 +1767,10 @@ function FoirProvider({
     [
       status,
       customer,
+      access,
+      accessStatus,
+      loadAccess,
+      ensureAccess,
       env,
       signIn,
       register,
@@ -1415,7 +1779,7 @@ function FoirProvider({
       signInWithProvider,
       completeProviderLogin,
       signOut2,
-      refresh,
+      refreshWithAccess,
       getToken,
       getProviders,
       hostedSignInUrl
@@ -1442,6 +1806,24 @@ function useFoirSession() {
 function useFoirUser() {
   return useFoirContext().customer;
 }
+function useFoirAccess() {
+  const { status, access, accessStatus, loadAccess, ensureAccess } = useFoirContext();
+  useEffect(() => {
+    if (status === "authenticated" && accessStatus === "idle") void ensureAccess();
+  }, [status, accessStatus, ensureAccess]);
+  const settled = status === "loading" ? "loading" : status === "unauthenticated" ? "ready" : accessStatus === "idle" ? "loading" : accessStatus;
+  return useMemo(
+    () => ({
+      status: settled,
+      isLoading: settled === "loading",
+      access,
+      hasRole: (key) => hasRole(access, key),
+      hasScope: (scope) => hasScope(access, scope),
+      reload: loadAccess
+    }),
+    [settled, access, loadAccess]
+  );
+}
 function useFoirAuth() {
   const {
     signIn,
@@ -2280,6 +2662,7 @@ export {
   SignIn,
   UserButton,
   createLocalStorageAdapter,
+  useFoirAccess,
   useFoirAuth,
   useFoirSession,
   useFoirUser

package/dist/server/events-client.d.ts

@@ -7,7 +7,7 @@
  *
  * const events = createEventsClient({
  *   apiUrl: process.env.PLATFORM_API_URL!,
- *   apiKey: process.env.FOIR_SECRET_KEY!, // sk_…, holding events:list.project
+ *   apiKey: process.env.FOIR_SECRET_KEY!, // sk_…, holding events:read
  * });
  *
  * const page = await events.list({ after: lastSeq, limit: 500 });
@@ -24,7 +24,7 @@
  * DECIDED 2026-08-04. The event log is reachable by an `sk_` api key
  * and by an admin session. It is NOT reachable by a customer token, there is no
  * customer lane for it on api-public, and a `pk_` key can never be minted
- * holding `events:list.project` at all.
+ * holding `events:read` at all.
  *
  * The reason is a predicate asymmetry rather than a policy preference.
  * `events.view` is plain tenant+project containment; `record.view` carries
@@ -81,7 +81,7 @@ export declare const FOIR_EVENTS_PATH = "/v1/events";
  * absent from the platform's `publicSafeScopeResources` — and never present in a
  * customer's resolved authority.
  */
-export declare const FOIR_EVENTS_SCOPE = "events:list.project";
+export declare const FOIR_EVENTS_SCOPE = "events:read";
 /**
  * The flat retention window, in days. Reported on every page as
  * {@link FoirEventRetention.windowDays} too; this constant is the one to compare
@@ -200,16 +200,16 @@ export interface FoirEventsClientConfig {
      */
     apiUrl: string;
     /**
-     * An `sk_` secret key holding `events:list.project`.
+     * An admin key holding `events:read`.
      *
-     * A `pk_` key is refused here rather than at the server — see the operator
-     * note at the top of this file.
+     * A publishable or a server key is refused here rather than at the server:
+     * see the operator note at the top of this file.
      */
     apiKey: string;
     /**
      * Extra headers. An `Authorization` header is refused: a customer bearer
      * flips api-public's resolved authority to the customer, and no customer
-     * authority can contain `events:list.project`.
+     * authority can contain `events:read`.
      */
     headers?: Readonly<Record<string, string>>;
     /** `fetch` implementation. Defaults to `globalThis.fetch`. */

package/dist/server/index.d.ts

@@ -1,6 +1,6 @@
 export { createServerClient, ServerClientError } from './server-client';
 export { verifyWebhookSignature } from './webhook-helpers';
-export { verifyScopedToken, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, type ScopedTokenClaims, type ScopedTokenSubject, type VerifyScopedTokenOptions, } from './verify-scoped-token';
+export { verifyScopedToken, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, recordsCreateModels, type ScopedTokenClaims, type ScopedTokenSubject, type VerifyScopedTokenOptions, } from './verify-scoped-token';
 export { createScopedTokenVerifier, ScopedTokenUnavailableError, type ScopedTokenVerifier, type ScopedTokenVerifierOptions, type ScopedTokenVerifierStats, } from './verify-scoped-token';
 export { requireScopedToken, ScopedTokenError, FOIR_TOKEN_HEADER, FOIR_CONTEXT_HEADER, type RequireScopedTokenOptions, type ScopedTokenIngress, } from './require-scoped-token';
 export { readDispatch, OperationPayloadError, type BodyCarrier, } from './read-dispatch';

package/dist/server/require-scoped-token.d.ts

@@ -18,7 +18,7 @@
  *
  * The verified token is also the endpoint's credential for calling Foir back.
  * `dispatch` on the result is the token as a data-client credential, so the
- * endpoint acts as the operation, with the capabilities the operation
+ * endpoint acts as the operation, with the grants the operation
  * declared, and holds no key of its own. `generated` is the module
  * `foir types --operation <key>` wrote for the operation:
  *

package/dist/server/server-client.d.ts

@@ -25,7 +25,7 @@ export declare class ServerClientError extends Error {
  *
  * const client = createServerClient({
  *   baseUrl: 'https://api.example.com',
- *   apiKey: 'sk_project_xxx',
+ *   apiKey: process.env.FOIR_ADMIN_KEY!, // foir_adm_...
  * });
  *
  * const { data } = await client.query('query { models { items { key } } }');

package/dist/server/verify-scoped-token.d.ts

@@ -24,26 +24,19 @@ export interface ScopedTokenClaims {
      * {@link parseSubject} to split into a typed object.
      */
     sub: string;
-    cap: Array<string>;
+    /**
+     * What the token carries, as grants in the permission catalogue's names:
+     * `records:read:<model>`, `records:write:<model>`,
+     * `records:create:<model>`, `users:create` and the rest. It is the whole of
+     * what the token may do. A token that does not say its grants is refused, so
+     * this is always set.
+     */
+    grants: Array<string>;
     jti: string;
     exp: number;
     nbf: number;
     iat: number;
     ctx?: Record<string, string>;
-    /**
-     * Records-read model allow-list. Present when the operation declared one
-     * or more `records:read:<model>` capabilities. Pair with the
-     * `records:read` marker in {@link ScopedTokenClaims.cap} to authorize a
-     * record read for a specific model.
-     */
-    rrm?: Array<string>;
-    /**
-     * Records-write model allow-list. Present when the operation declared
-     * one or more `records:write:<model>` capabilities. Pair with the
-     * `records:write` marker in {@link ScopedTokenClaims.cap} to authorize
-     * a record write for a specific model.
-     */
-    rwm?: Array<string>;
     /**
      * The customer the token acts for, when it acts for one: the signed-in
      * customer who ran the operation, or the owner of the record whose event
@@ -77,19 +70,21 @@ export interface ScopedTokenSubject {
  */
 export declare function parseSubject(sub: string): ScopedTokenSubject;
 /**
- * Extract the `records:read:<model>` allow-list from a verified claim
- * set. Returns an empty array when the token grants no per-model read
- * capabilities. Convenience over reading {@link ScopedTokenClaims.rrm}
- * directly, mirroring the platform's
- * `scopedtoken.Claims.RecordsReadModels` field.
+ * The models a verified token may read records of: each model a
+ * `records:read:<model>` grant names. Empty when it names none.
  */
 export declare function recordsReadModels(claims: ScopedTokenClaims): Array<string>;
 /**
- * Extract the `records:write:<model>` allow-list from a verified claim
- * set. Returns an empty array when the token grants no per-model write
- * capabilities. Mirror of {@link recordsReadModels} for the write side.
+ * The models a verified token may change records of: each model a
+ * `records:write:<model>` grant names. Changing a record and making one are
+ * two permissions: see {@link recordsCreateModels}.
  */
 export declare function recordsWriteModels(claims: ScopedTokenClaims): Array<string>;
+/**
+ * The models a verified token may make records of: each model a
+ * `records:create:<model>` grant names.
+ */
+export declare function recordsCreateModels(claims: ScopedTokenClaims): Array<string>;
 export interface VerifyScopedTokenOptions {
     /**
      * Expected `iss` claim. Defaults to `'foir-platform'`, the issuer the