@foir/sdk 0.19.0 → 0.21.0

package/dist/server.js

@@ -72,6 +72,165 @@ async function verifyWebhookSignature(payload, signature, secret) {
   return mismatch === 0;
 }
 
+// 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 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;
+}
+function hasReach(permission, reach) {
+  const reaches = permission[2];
+  return reaches.length === 0 ? reach === "own" : reaches.includes(reach);
+}
+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;
+}
+
 // src/server/verify-scoped-token.ts
 var JWKS_CACHE_TTL_MS = 5 * 60 * 1e3;
 function getCache() {
@@ -129,11 +288,26 @@ function parseSubject(sub) {
   }
   return { tenantId, projectId, appName: sub.slice(second + 1) };
 }
+function modelsFor(claims, permission) {
+  const out = [];
+  for (const grant of claims.grants) {
+    const parsed = parseGrant(grant);
+    if (!parsed || parsed.permission[0] !== permission || parsed.target === "") continue;
+    if (!out.includes(parsed.target)) out.push(parsed.target);
+  }
+  return out;
+}
 function recordsReadModels(claims) {
-  return claims.rrm ?? [];
+  return modelsFor(claims, "records:read");
 }
 function recordsWriteModels(claims) {
-  return claims.rwm ?? [];
+  return modelsFor(claims, "records:write");
+}
+function recordsCreateModels(claims) {
+  return modelsFor(claims, "records:create");
+}
+function strings(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
 async function verifyScopedToken(token, jwksUrl, options) {
   return verifyWithKeys(token, () => loadJwks(jwksUrl), void 0, options);
@@ -169,12 +343,13 @@ async function verifyWithKeys(token, loadKeys, refetchForUnknownKid, options) {
     )
   );
   if (!ok) throw new Error("signature invalid");
-  let claims;
+  let payload;
   try {
-    claims = JSON.parse(new TextDecoder().decode(base64UrlDecode(rawPayload)));
+    payload = JSON.parse(new TextDecoder().decode(base64UrlDecode(rawPayload)));
   } catch {
     throw new Error("unreadable token payload");
   }
+  const claims = { ...payload, grants: strings(payload.grants) };
   const now = Math.floor((options?.now?.() ?? Date.now()) / 1e3);
   if (claims.iss !== expectedIssuer) throw new Error(`bad iss ${claims.iss}`);
   if (typeof claims.exp !== "number" || claims.exp < now) {
@@ -183,6 +358,7 @@ async function verifyWithKeys(token, loadKeys, refetchForUnknownKid, options) {
   if (typeof claims.nbf === "number" && claims.nbf > now + 30) {
     throw new Error("token not yet valid");
   }
+  if (!("grants" in payload)) throw new Error("the token says no grants");
   return claims;
 }
 function parseContextHeader(raw) {
@@ -618,6 +794,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"
@@ -835,12 +1033,26 @@ async function hmacSha256Hex(secret, body) {
   return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// 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;
+}
+
 // src/data/transport.ts
 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;
@@ -1241,7 +1453,7 @@ function describe2(payload) {
 
 // src/server/events-client.ts
 var FOIR_EVENTS_PATH = "/v1/events";
-var FOIR_EVENTS_SCOPE = "events:list.project";
+var FOIR_EVENTS_SCOPE = "events:read";
 var FOIR_EVENTS_RETENTION_DAYS = 90;
 var FoirEventCursorExpiredError = class extends FoirRequestError {
   /**
@@ -1277,17 +1489,18 @@ function assertOperatorKey(apiKey) {
   const key = apiKey?.trim() ?? "";
   if (!key) {
     throw new FoirRequestError(
-      `[foir] createEventsClient: apiKey is empty \u2014 pass an sk_ secret key holding ${FOIR_EVENTS_SCOPE}.`
+      `[foir] createEventsClient: apiKey is empty. Pass an admin key holding ${FOIR_EVENTS_SCOPE}.`
     );
   }
-  if (key.startsWith("pk_")) {
+  const kind = foirKeyKind(key);
+  if (kind === "publishable" || kind === "server") {
     throw new FoirRequestError(
-      `[foir] createEventsClient: the event log is an OPERATOR surface and a public (pk_) key can never hold ${FOIR_EVENTS_SCOPE} \u2014 it is not mintable on a public key. Use an sk_ secret key from a server-side runtime; a pk_ key is embeddable in browser bundles, and the log names which customer acted on records the bundle's reader cannot themselves read.`
+      `[foir] createEventsClient: the event log is an OPERATOR surface and a ${kind} key can never hold ${FOIR_EVENTS_SCOPE}: it is not mintable on an app's key. Use an admin key from a machine of your own. The log names which customer acted on records that whoever reads an app's key cannot themselves read.`
     );
   }
-  if (!key.startsWith("sk_")) {
+  if (kind === void 0) {
     throw new FoirRequestError(
-      `[foir] createEventsClient: apiKey must be an sk_ secret key, got a key starting "${key.slice(0, 4)}". The event log is reachable by an sk_ api key or an admin session only.`
+      `[foir] createEventsClient: apiKey must be an admin key, got a key starting "${key.slice(0, 4)}". The event log is reachable by an admin key or an admin session only.`
     );
   }
   return key;
@@ -1529,6 +1742,7 @@ export {
   parseContextHeader,
   parseSubject,
   readDispatch,
+  recordsCreateModels,
   recordsReadModels,
   recordsWriteModels,
   requireScopedToken,

package/dist/transport/foir-http.d.ts

@@ -273,8 +273,8 @@ export interface FoirKeyHeaderInput {
      * freshly pushed model changes (new fields, new models) are visible at
      * runtime — otherwise selections on draft-only fields are silently stripped
      * and surface as confusing "fragment never used" errors. The header has no
-     * effect under public keys (the server ignores it), so it is safe to send
-     * whenever the caller is in preview.
+     * effect under an app's key without `drafts:read` (the server ignores it),
+     * so it is safe to send whenever the caller is in preview.
      */
     draftChannel?: boolean;
     bearerToken?: string;
@@ -343,8 +343,28 @@ export declare function refuseCredentialHeaders(extra: Readonly<Record<string, s
 /** The header a server names the visitor it calls for in. */
 export declare const FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 /**
- * The address of the visitor a server rendering pages is calling for, or a
- * function that resolves it for each request.
+ * The visitor a server rendering pages is calling for: who they are to the
+ * per-visitor limits, and where they are to location targeting.
+ *
+ * Each part is what your host says of the visitor, and each is optional. A
+ * part left out is not said: with no address the request counts as your
+ * server's own, and with no country and no coordinates the visitor is one
+ * nobody could place. Where your server is never stands in for where the
+ * visitor is.
+ */
+export interface FoirVisitor {
+    /** The visitor's address, sent as `X-Foir-Visitor-IP`. */
+    address?: string | null;
+    /** The visitor's country, as an ISO 3166-1 alpha-2 code such as `GB`. */
+    country?: string | null;
+    /** The visitor's latitude, in decimal degrees. Sent with `longitude`, or not at all. */
+    latitude?: number | null;
+    /** The visitor's longitude, in decimal degrees. Sent with `latitude`, or not at all. */
+    longitude?: number | null;
+}
+/**
+ * The visitor a server rendering pages is calling for, or a function that
+ * resolves them for each request. A string is the visitor's address alone.
  *
  * The SDK does not read it off a request, because which request header holds
  * the visitor's real address, and whether a visitor can forge it, depends on
@@ -352,7 +372,26 @@ export declare const FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
  * strips; that value, and only that, belongs here. A function that yields
  * nothing sends nothing, and the API counts the request as your server's own.
  */
-export type FoirVisitorSource = string | (() => string | null | undefined | Promise<string | null | undefined>);
+export type FoirVisitorSource = string | FoirVisitor | (() => string | FoirVisitor | null | undefined | Promise<string | FoirVisitor | null | undefined>);
+/** Where a stated visitor is, as a read's `contexts` carries it. */
+export interface FoirVisitorPlace {
+    country?: string;
+    location?: {
+        latitude: number;
+        longitude: number;
+    };
+}
+/** One request's visitor, resolved: the address for the header, and the place for the read. */
+export interface FoirResolvedVisitor {
+    address?: string;
+    place: FoirVisitorPlace;
+}
+/**
+ * Resolve a `visitor` for one request. The provider is called here, once, and
+ * what it yields is used for the header and for the read alike, so the two
+ * never describe different visitors.
+ */
+export declare function resolveFoirVisitor(source: FoirVisitorSource | undefined): Promise<FoirResolvedVisitor>;
 export declare function buildFoirHeaders(input: FoirHeaderInput): Record<string, string>;
 /**
  * Build a `/v1/...` URL from whatever the caller put in `apiUrl`.

package/dist/transport/key-kind.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The kind a key says it is, by its prefix.
+ *
+ * A key is one of three kinds, chosen by whoever made it. A publishable key
+ * sits in a page or an app. A server key is held by the server that renders an
+ * app's pages. An admin key is a machine's own: a sync job, a pipeline, a tool.
+ * A key says its kind in its first letters, so this is decided without a
+ * request.
+ *
+ * A key minted before a key had a kind says an older type. A `pk_` key is a
+ * publishable key. An `sk_` or a `tc_` key says only that it is not public:
+ * the platform holds it as an admin key, and it is reported here as `older`,
+ * so that a caller who refuses an admin key by name does not refuse a key
+ * whose holder has not yet been able to mint a server key in its place.
+ */
+export type FoirKeyKind = 'publishable' | 'server' | 'admin';
+/** What a key's prefix says of it: its kind, or that it is an older secret. */
+export type FoirKeyPrefixKind = FoirKeyKind | 'older';
+/** Where each credential is for, and which key an app holds. */
+export declare const FOIR_CREDENTIALS_DOC = "https://docs.foir.dev/credentials";
+/**
+ * What a key says of itself by its prefix, or `undefined` for a string that
+ * is no key Fóir made.
+ */
+export declare function foirKeyKind(apiKey: string | null | undefined): FoirKeyPrefixKind | undefined;
+/**
+ * What an app's client says when it is handed an admin key, naming the client
+ * it was handed to. An admin key is a machine's own, so every client an app
+ * builds refuses one before any request, in the same words.
+ *
+ * Only a key that says it is an admin key by its prefix is refused. A key
+ * minted before a key had a kind does not say, and is let through.
+ */
+export declare function adminKeyRefusal(client: string): string;
+/**
+ * Whether a key may be named in a URL. Only a publishable key may: it ships in
+ * the page and is served to every visitor, so naming it discloses nothing. Any
+ * other key would land in access logs, referrer headers and browser history.
+ */
+export declare function isPublishableFoirKey(apiKey: string | null | undefined): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -177,18 +177,19 @@
     "ws": "^8.18.0",
     "y-websocket": "^3.0.0",
     "yjs": "^13.6.30",
+    "@foir/access-vocab": "0.0.0",
     "@foir/proto-ts": "0.109.0"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "node scripts/generate-app-vocabulary.mjs && node scripts/clean-dist.mjs && tsup && tsc -p tsconfig.build.json && node scripts/bundle-app-contract-types.mjs && node scripts/assert-export-types.mjs && node scripts/assert-public-exports.mjs",
+    "build": "node scripts/generate-app-vocabulary.mjs && node scripts/generate-grant-table.mjs && node scripts/clean-dist.mjs && tsup && tsc -p tsconfig.build.json && node scripts/bundle-app-contract-types.mjs && node scripts/assert-export-types.mjs && node scripts/assert-public-exports.mjs",
     "snapshot:exports": "node scripts/assert-public-exports.mjs --update",
     "dev": "node scripts/dev-watch.mjs",
-    "check-types": "node scripts/generate-app-vocabulary.mjs && tsc --noEmit",
-    "test": "node scripts/generate-app-vocabulary.mjs && vitest run",
-    "test:watch": "node scripts/generate-app-vocabulary.mjs && vitest watch",
+    "check-types": "node scripts/generate-app-vocabulary.mjs && node scripts/generate-grant-table.mjs && tsc --noEmit",
+    "test": "node scripts/generate-app-vocabulary.mjs && node scripts/generate-grant-table.mjs && vitest run",
+    "test:watch": "node scripts/generate-app-vocabulary.mjs && node scripts/generate-grant-table.mjs && vitest watch",
     "release:patch": "pnpm version patch",
     "release:minor": "pnpm version minor",
     "release:major": "pnpm version major"