@foir/sdk 0.20.0 → 0.21.0

package/dist/server.js

@@ -74,10 +74,10 @@ async function verifyWebhookSignature(payload, signature, secret) {
 
 // src/auth/grant-table.generated.ts
 var GRANT_TABLE = [
-  ["records:read", true, ["own", "named", "all"], []],
+  ["records:read", true, ["own", "all"], []],
   ["records:create", true, [], []],
-  ["records:write", true, ["own", "named", "all"], []],
-  ["records:delete", true, ["own", "named", "all"], []],
+  ["records:write", true, ["own", "all"], []],
+  ["records:delete", true, ["own", "all"], []],
   ["records:publish", true, ["own", "all"], []],
   ["records:attribute", true, [], []],
   ["search:read", true, [], []],
@@ -93,8 +93,8 @@ var GRANT_TABLE = [
   ["notifications:consent", false, [], []],
   ["pushcredentials:read", false, [], []],
   ["pushcredentials:write", false, [], []],
-  ["notes:read", false, [], []],
-  ["notes:write", false, [], []],
+  ["notes:read", false, ["own", "all"], []],
+  ["notes:write", false, ["own", "all"], []],
   ["notes:create", false, [], []],
   ["approvals:read", false, [], []],
   ["approvals:write", false, [], []],
@@ -151,7 +151,7 @@ var GRANT_TABLE = [
   ["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", "notes:write", "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"]],
+  ["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, [], []],
@@ -167,7 +167,7 @@ var GRANT_TABLE = [
   ["tenanthooks:read", false, [], []],
   ["tenanthooks:write", false, [], []],
   ["apps:install", false, [], []],
-  ["tenant:manage", false, [], ["project:manage", "projects:create", "projects:delete", "tenants:read", "tenants:write", "tenants:delete", "audit:read", "export:run", "billing:read", "billing:manage", "usage:read", "controlkeys:read", "controlkeys:write", "tenanthooks:read", "tenanthooks:write", "apps:install"]],
+  ["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, [], []],
@@ -231,49 +231,6 @@ function parseGrant(s) {
   return null;
 }
 
-// src/server/older-claims.generated.ts
-var OLDER_CLAIM_TARGET = "{target}";
-var OLDER_CAPABILITY_GRANTS = {
-  "config:read": ["appconfig:read"],
-  "customers:read": ["users:read.all"],
-  "customers:read:identity": ["identities:read"],
-  "customers:read:named": ["users:read.named"],
-  "customers:write": ["users:create"],
-  "embeddings:read": ["embeddings:read"],
-  "embeddings:write": ["embeddings:write"],
-  "files:delete": ["files:delete"],
-  "files:list": ["files:read"],
-  "files:read": ["files:read"],
-  "files:write": ["files:write"],
-  "notifications:consent": ["notifications:consent"],
-  "notifications:read": ["notifications:read"],
-  "notifications:write": ["notifications:write.named"],
-  "operations:complete": ["operations:complete"],
-  "records:attribute": ["records:attribute"],
-  "records:attribute:{target}": ["records:attribute:{target}"],
-  "records:delete": [],
-  "records:delete:{target}": ["records:delete:{target}"],
-  "records:publish": [],
-  "records:publish:{target}": ["records:publish:{target}"],
-  "records:read": [],
-  "records:read:{target}": ["records:read:{target}"],
-  "records:write": [],
-  "records:write:{target}": ["records:write.all:{target}", "records:create:{target}"],
-  "secrets:delete.app": ["appsecrets:delete"],
-  "secrets:delete.customer": ["usersecrets:delete"],
-  "secrets:delete.project": ["secrets:delete"],
-  "secrets:list.app": ["appsecrets:list"],
-  "secrets:list.customer": ["usersecrets:list"],
-  "secrets:list.project": ["secrets:list"],
-  "secrets:put.app": ["appsecrets:put"],
-  "secrets:put.customer": ["usersecrets:put"],
-  "secrets:put.project": ["secrets:put"],
-  "secrets:read.app": ["appsecrets:read"],
-  "secrets:read.customer": ["usersecrets:read"],
-  "secrets:read.project": ["secrets:read"],
-  "status:write": ["status:write"]
-};
-
 // src/server/verify-scoped-token.ts
 var JWKS_CACHE_TTL_MS = 5 * 60 * 1e3;
 function getCache() {
@@ -349,49 +306,9 @@ function recordsWriteModels(claims) {
 function recordsCreateModels(claims) {
   return modelsFor(claims, "records:create");
 }
-var OLDER_RECORD_LANES = [
-  ["records:read", "rrm"],
-  ["records:write", "rwm"],
-  ["records:delete", "rdm"],
-  ["records:publish", "rpm"]
-];
 function strings(value) {
   return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
-function worthBefore(capability) {
-  if (Object.hasOwn(OLDER_CAPABILITY_GRANTS, capability)) return OLDER_CAPABILITY_GRANTS[capability] ?? [];
-  for (const [form, grants] of Object.entries(OLDER_CAPABILITY_GRANTS)) {
-    if (!form.endsWith(OLDER_CLAIM_TARGET)) continue;
-    const prefix = form.slice(0, -OLDER_CLAIM_TARGET.length);
-    if (capability.startsWith(prefix) && capability.length > prefix.length) {
-      const model = capability.slice(prefix.length);
-      return grants.map((grant) => grant.replace(OLDER_CLAIM_TARGET, model));
-    }
-  }
-  return [];
-}
-var OLDER_WRITE = "records:write";
-var OLDER_DELETE = "records:delete";
-var OLDER_CREATE = "customers:write";
-function grantsOfOlderClaims(payload) {
-  const cap = strings(payload.cap);
-  const written = new Set(cap.includes(OLDER_WRITE) ? strings(payload.rwm) : []);
-  const grants = [];
-  for (const [marker, claim] of OLDER_RECORD_LANES) {
-    if (!cap.includes(marker)) continue;
-    for (const model of strings(payload[claim])) {
-      if (marker !== OLDER_WRITE && written.has(model)) grants.push(`${marker}.all:${model}`);
-      else grants.push(...worthBefore(`${marker}:${model}`));
-    }
-  }
-  for (const capability of cap) {
-    if (!OLDER_RECORD_LANES.some(([marker]) => marker === capability)) grants.push(...worthBefore(capability));
-  }
-  if (cap.includes(OLDER_CREATE) && cap.includes(OLDER_DELETE) && strings(payload.rdm).length > 0) {
-    grants.push("identities:delete");
-  }
-  return grants;
-}
 async function verifyScopedToken(token, jwksUrl, options) {
   return verifyWithKeys(token, () => loadJwks(jwksUrl), void 0, options);
 }
@@ -432,10 +349,7 @@ async function verifyWithKeys(token, loadKeys, refetchForUnknownKid, options) {
   } catch {
     throw new Error("unreadable token payload");
   }
-  const claims = {
-    ...payload,
-    grants: "grants" in payload ? strings(payload.grants) : grantsOfOlderClaims(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) {
@@ -444,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) {
@@ -879,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"
@@ -1096,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;
@@ -1538,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;

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.20.0",
+  "version": "0.21.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {

package/dist/server/older-claims.generated.d.ts

@@ -1,8 +0,0 @@
-/** Stands, below, where a capability or a grant names a model. */
-export declare const OLDER_CLAIM_TARGET = "{target}";
-/**
- * What each capability a token said before it said its grants was worth, as
- * the platform reads one. A capability that was worth nothing is worth nothing
- * here.
- */
-export declare const OLDER_CAPABILITY_GRANTS: Readonly<Record<string, readonly string[]>>;