@foir/sdk 0.22.0 → 0.23.0

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:read
+ *   apiKey: process.env.FOIR_SECRET_KEY!, // an admin key, holding events:read
  * });
  *
  * const page = await events.list({ after: lastSeq, limit: 500 });
@@ -21,9 +21,9 @@
  * PROJECT SURFACE. Your app's users do not reach it.
  * ---------------------------------------------------------------------------
  *
- * DECIDED 2026-08-04. The event log is reachable by an `sk_` api key
+ * DECIDED 2026-08-04. The event log is reachable by an admin key
  * and by a console session. It is NOT reachable by a user token, there is no
- * user lane for it on api-public, and a `pk_` key can never be minted
+ * user lane for it on api-public, and a publishable key can never be minted
  * holding `events:read` at all.
  *
  * The reason is a predicate asymmetry rather than a policy preference.
@@ -39,19 +39,19 @@
  *
  *   1. **It lives on `@foir/sdk/server` and nowhere else.** Not `./data`, not
  *      `./client`, not `./react`. Those subpaths are the ones a storefront
- *      bundles, and `./data` in particular is routinely constructed with a `pk_`
+ *      bundles, and `./data` in particular is routinely constructed with a publishable key
  *      key in browser-reachable code. `src/server/__tests__/events-client.test.ts`
  *      walks the import graph of every published subpath and fails if this
  *      module becomes reachable from one that ships to a browser — because
  *      "we only documented it on the server" is not a property anything checks.
  *
- *   2. **A `pk_` key is refused at construction**, before a request is made. The
+ *   2. **A publishable key is refused at construction**, before a request is made. The
  *      server would refuse it anyway (403), but a 403 at 3am in a deploy log is
  *      a worse teacher than a thrown error naming the key type at the line that
  *      built the client.
  *
  *   3. **There is no `bearerToken` option, and an `Authorization` header is
- *      refused.** On api-public a request presenting `sk_` plus a user
+ *      refused.** On api-public a request presenting an admin key plus a user
  *      bearer resolves the USER as the authority, and `events` is stripped
  *      from every user authority upstream — so attaching a signed-in
  *      shopper's token to a project read turns a working call into a 403 that
@@ -77,7 +77,7 @@ import { type FoirReconnectPolicy, type FoirSubscription, type FoirSubscriptionH
 /** The path `GET /v1/events` is mounted on, inside api-public's api-key group. */
 export declare const FOIR_EVENTS_PATH = "/v1/events";
 /**
- * The scope an `sk_` key must hold. Never mintable on a `pk_` — `events` is
+ * The scope an admin key must hold. Never mintable on a publishable key: `events` is
  * absent from the platform's `publicSafeScopeResources` — and never present in a
  * user's resolved authority.
  */

package/dist/server/types.d.ts

@@ -7,7 +7,7 @@
 export interface ServerClientOptions {
     /** Base URL for the platform API (e.g., 'https://api.example.com'). */
     baseUrl: string;
-    /** Project-scoped API key (sk_* format). */
+    /** A project's admin key (foir_adm_). */
     apiKey: string;
     /**
      * Optional config key. Retained for backwards compatibility with older

package/dist/server.js

@@ -74,123 +74,123 @@ async function verifyWebhookSignature(payload, signature, secret) {
 
 // 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:stand", false, [], []],
-  ["project:manage", false, [], ["project:stand", "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:setup", "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, [], []],
-  ["tenantsigninproviders:read", false, [], []],
-  ["tenantsigninproviders: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", "tenantsigninproviders:read", "tenantsigninproviders:write", "apps:install"]],
-  ["platform:read", false, [], []],
-  ["platform:manage", false, [], ["tenant:manage", "platform:read", "platform:create_workspace"]],
-  ["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, [], []]
+  ["records:read", "model", ["own", "all"], []],
+  ["records:create", "model", [], []],
+  ["records:write", "model", ["own", "all"], []],
+  ["records:delete", "model", ["own", "all"], []],
+  ["records:publish", "model", ["own", "all"], []],
+  ["records:attribute", "model", [], []],
+  ["search:read", "model", [], []],
+  ["embeddings:read", "none", [], []],
+  ["embeddings:write", "none", [], []],
+  ["schemas:read", "none", [], []],
+  ["drafts:read", "none", [], []],
+  ["files:read", "none", ["own", "all"], []],
+  ["files:write", "none", ["own", "all"], []],
+  ["files:delete", "none", ["own", "all"], []],
+  ["notifications:read", "none", ["own", "all"], []],
+  ["notifications:write", "none", ["own", "named", "all"], []],
+  ["notifications:consent", "none", [], []],
+  ["pushcredentials:read", "none", [], []],
+  ["pushcredentials:write", "none", [], []],
+  ["notes:read", "none", ["own", "all"], []],
+  ["notes:write", "none", ["own", "all"], []],
+  ["notes:create", "none", [], []],
+  ["approvals:read", "none", [], []],
+  ["approvals:write", "none", [], []],
+  ["rooms:read", "model", [], []],
+  ["rooms:write", "model", [], []],
+  ["presence:read", "model", [], []],
+  ["operations:read", "none", [], []],
+  ["operations:execute", "operation", [], []],
+  ["operations:write", "none", [], []],
+  ["operations:complete", "none", [], []],
+  ["status:write", "none", [], []],
+  ["appconfig:read", "none", [], []],
+  ["schedules:read", "none", [], []],
+  ["schedules:write", "none", [], []],
+  ["hooks:read", "none", [], []],
+  ["hooks:write", "none", [], []],
+  ["authclients:read", "none", [], []],
+  ["authclients:write", "none", [], []],
+  ["domains:read", "none", [], []],
+  ["domains:write", "none", [], []],
+  ["secrets:read", "none", [], []],
+  ["secrets:list", "none", [], []],
+  ["secrets:put", "none", [], []],
+  ["secrets:delete", "none", [], []],
+  ["appsecrets:read", "none", [], []],
+  ["appsecrets:list", "none", [], []],
+  ["appsecrets:put", "none", [], []],
+  ["appsecrets:delete", "none", [], []],
+  ["opsecrets:read", "none", [], []],
+  ["opsecrets:write", "none", [], []],
+  ["settings:read", "none", [], []],
+  ["settings:write", "none", [], []],
+  ["designtokens:read", "none", [], []],
+  ["designtokens:write", "none", [], []],
+  ["models:read", "none", [], []],
+  ["models:write", "none", [], []],
+  ["configs:read", "none", [], []],
+  ["configs:write", "none", [], []],
+  ["apps:read", "none", [], []],
+  ["apps:write", "none", [], []],
+  ["events:read", "none", [], []],
+  ["targeting:debug", "none", [], []],
+  ["visitors:forward", "none", [], []],
+  ["apikeys:read", "none", [], []],
+  ["apikeys:write", "none", [], []],
+  ["organizations:read", "none", [], []],
+  ["organizations:write", "none", [], []],
+  ["organizations:create", "none", [], []],
+  ["organizations:delete", "none", [], []],
+  ["organizations:reach", "none", [], []],
+  ["members:read", "none", [], []],
+  ["members:write", "none", [], []],
+  ["roles:read", "none", [], []],
+  ["roles:write", "none", [], []],
+  ["projects:read", "none", [], []],
+  ["projects:write", "none", [], []],
+  ["project:stand", "none", [], []],
+  ["project:manage", "none", [], ["project:stand", "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:setup", "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", "authclients:read", "authclients: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", "none", [], []],
+  ["projects:delete", "none", [], []],
+  ["tenants:read", "none", [], []],
+  ["tenants:write", "none", [], []],
+  ["tenants:delete", "none", [], []],
+  ["audit:read", "none", [], []],
+  ["export:run", "none", [], []],
+  ["billing:read", "none", [], []],
+  ["billing:manage", "none", [], []],
+  ["usage:read", "none", [], []],
+  ["controlkeys:read", "none", [], []],
+  ["controlkeys:write", "none", [], []],
+  ["tenanthooks:read", "none", [], []],
+  ["tenanthooks:write", "none", [], []],
+  ["apps:install", "none", [], []],
+  ["tenant:manage", "none", [], ["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", "none", [], []],
+  ["platform:manage", "none", [], ["tenant:manage", "platform:read", "platform:create_workspace"]],
+  ["platform:create_workspace", "none", [], []],
+  ["users:read", "none", ["own", "named", "all"], []],
+  ["users:write", "none", ["own", "all"], []],
+  ["users:setup", "none", [], []],
+  ["users:delete", "none", ["own", "all"], []],
+  ["users:create", "none", [], []],
+  ["identities:read", "none", [], []],
+  ["identities:delete", "none", [], []],
+  ["usersecrets:read", "none", [], []],
+  ["usersecrets:list", "none", [], []],
+  ["usersecrets:put", "none", [], []],
+  ["usersecrets:delete", "none", [], []],
+  ["auth:login_with_foir", "none", [], []],
+  ["signinproviders:read", "none", [], []],
+  ["signinproviders:write", "none", [], []]
 ];
 
 // src/auth/grants.ts
+var FIELD_PERMISSIONS = ["records:read", "records:write"];
+var FIELD_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var index;
 function catalogue() {
   if (!index) {
@@ -226,8 +226,12 @@ function parseGrant(s) {
     let target = "";
     if (rest.startsWith(":")) {
       target = rest.slice(1);
-      if (!permission[1]) return null;
+      if (permission[1] === "none") return null;
       if (target === "" || /[: \t\n*]/.test(target)) return null;
+      const dot = target.indexOf(".");
+      if (permission[1] === "model" && dot >= 0) {
+        if (!FIELD_PERMISSIONS.includes(name) || dot === 0 || !FIELD_KEY.test(target.slice(dot + 1))) return null;
+      }
     }
     return { permission, reach, target };
   }
@@ -1040,10 +1044,7 @@ async function hmacSha256Hex(secret, body) {
 var KEY_PREFIXES = [
   ["foir_pub_", "publishable"],
   ["foir_srv_", "server"],
-  ["foir_adm_", "admin"],
-  ["pk_", "publishable"],
-  ["sk_", "older"],
-  ["tc_", "older"]
+  ["foir_adm_", "admin"]
 ];
 function foirKeyKind(apiKey) {
   if (typeof apiKey !== "string") return void 0;
@@ -1513,7 +1514,7 @@ function assertNoBearer(headers) {
   for (const name of Object.keys(headers)) {
     if (name.toLowerCase() === "authorization") {
       throw new FoirRequestError(
-        `[foir] createEventsClient: an Authorization header is not accepted. A user bearer makes the user the resolved authority on api-public, and no user authority can contain ${FOIR_EVENTS_SCOPE}. The sk_ key alone is the credential for this surface.`
+        `[foir] createEventsClient: an Authorization header is not accepted. A user bearer makes the user the resolved authority on api-public, and no user authority can contain ${FOIR_EVENTS_SCOPE}. The admin key alone is the credential for this surface.`
       );
     }
   }

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

@@ -31,7 +31,7 @@ export interface FoirEnv {
  *
  * Preview is selected at the environment level, not per-request: load a
  * preview env file that sets `FOIR_PREVIEW=true` + the preview environment's
- * own `pk_…` key holding `drafts:read` as `PLATFORM_PREVIEW_API_KEY`, instead
+ * own publishable key holding `drafts:read` as `PLATFORM_PREVIEW_API_KEY`, instead
  * of the default env.
  * The site-wide mode keeps draft semantics consistent — every loader sees
  * the same preview/published view of the world. Intended for non-production

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

@@ -6,30 +6,19 @@
  * 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;
+export declare function foirKeyKind(apiKey: string | null | undefined): FoirKeyKind | 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;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -177,8 +177,8 @@
     "ws": "^8.18.0",
     "y-websocket": "^3.0.0",
     "yjs": "^13.6.30",
-    "@foir/proto-ts": "0.109.0",
-    "@foir/access-vocab": "0.0.0"
+    "@foir/access-vocab": "0.0.0",
+    "@foir/proto-ts": "0.109.0"
   },
   "engines": {
     "node": ">=18.0.0"