@foir/sdk 0.19.0 → 0.21.0

package/dist/placement.js

@@ -1,3 +1,197 @@
+// 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/placement/index.ts
 var PLACEMENT_MESSAGE = {
   /** Page to console: the page is listening and wants a token. */
@@ -13,6 +207,27 @@ var PLACEMENT_MESSAGE = {
   /** Console to page: how the console looks, now and whenever it changes. */
   appearance: "foir:placement:appearance"
 };
+function strings(value) {
+  return Array.isArray(value) ? value.filter((v) => typeof v === "string") : null;
+}
+function reasons(value) {
+  if (!Array.isArray(value)) return null;
+  const out = [];
+  for (const entry of value) {
+    const e = entry;
+    if (typeof e?.grant === "string") out.push({ grant: e.grant, reason: typeof e.reason === "string" ? e.reason : "" });
+  }
+  return out;
+}
+function grantFrom(sent) {
+  return {
+    accessToken: sent.accessToken,
+    expiresAt: sent.expiresAt,
+    orgId: sent.orgId,
+    grants: strings(sent.grants) ?? [],
+    withheldGrants: reasons(sent.withheldGrants) ?? []
+  };
+}
 var FOIR_CONSOLE_ORIGINS = {
   production: ["https://app.foir.io"],
   dev: ["https://app-dev.foir.io"]
@@ -87,7 +302,9 @@ function connectPlacement(options) {
       get appearance() {
         return appearance;
       },
-      can: (scope) => grant?.grantedScopes.includes(scope) ?? false,
+      // As written, for a list a console of the release before sent in the
+      // names a placement declared then; and by what the list covers.
+      can: (asked) => grant ? grant.grants.includes(asked) || holds(grant.grants, asked) : false,
       async request(document, variables) {
         if (!grant) throw new PlacementRefused("the operator has signed out");
         const res = await doFetch(`${apiUrl}/graphql`, {
@@ -113,7 +330,7 @@ function connectPlacement(options) {
       const msg = event.data;
       switch (msg.type) {
         case PLACEMENT_MESSAGE.token:
-          grant = msg.grant;
+          grant = grantFrom(msg.grant);
           scheduleRefresh();
           if (!settled) {
             settled = true;

package/dist/push.js

@@ -1,6 +1,30 @@
 // 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"]
+];
+var FOIR_CREDENTIALS_DOC = "https://docs.foir.dev/credentials";
+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 adminKeyRefusal(client) {
+  return `[foir] ${client} was given an admin key. An admin key is a machine's own: nobody signs in through it, and an app never holds one. Build this client from your publishable key, or from your server key on the server that renders your pages. A machine that acts for itself uses createServerClient from @foir/sdk/server. See ${FOIR_CREDENTIALS_DOC}`;
+}
+function isPublishableFoirKey(apiKey) {
+  return foirKeyKind(apiKey) === "publishable";
+}
+
 // src/graphql/cdn-route.ts
 import { print } from "graphql";
 
@@ -125,6 +149,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"
@@ -277,7 +323,7 @@ function isCdnEligible(env, documentText, bearerToken, orgId) {
   if (orgId) return false;
   if (isFoirPreview(env)) return false;
   const apiKey = resolveFoirApiKey(env);
-  if (!apiKey?.startsWith("pk_")) return false;
+  if (!isPublishableFoirKey(apiKey)) return false;
   return !/\bmutation\b/.test(documentText);
 }
 
@@ -290,6 +336,9 @@ async function foirRequest(env, document, variables, options) {
       "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
     );
   }
+  if (foirKeyKind(apiKey) === "admin") {
+    throw new FoirRequestError(adminKeyRefusal("foirRequest"));
+  }
   const headers = buildFoirHeaders({
     apiKey,
     draftChannel: isFoirPreview(env),
@@ -852,10 +901,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;
@@ -896,7 +942,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" };
@@ -1034,6 +1080,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",

package/dist/react/FoirProvider.d.ts

@@ -1,13 +1,25 @@
 import type { ReactNode } from 'react';
-import type { AuthProviderPublic, FoirCustomer, FoirSessionConfig, SessionAdapter } from '../auth';
+import type { AuthProviderPublic, FoirAccess, FoirCustomer, FoirSessionConfig, SessionAdapter } from '../auth';
 import type { ProviderCallbackInput, ProviderLoginInput } from '../auth';
 import type { FoirEnv } from '../graphql/foir-request';
 /** Where the session hydration stands. */
 export type FoirStatus = 'loading' | 'authenticated' | 'unauthenticated';
+/**
+ * Where reading the signed-in customer's access stands. `idle` until something
+ * asks for it; `unavailable` when the platform could not be asked.
+ */
+export type FoirAccessStatus = 'idle' | 'loading' | 'ready' | 'unavailable';
 /** The full context value. Read it through the hooks below, not directly. */
 export interface FoirContextValue {
     status: FoirStatus;
     customer: FoirCustomer | null;
+    /** The signed-in customer's access, once read. See {@link useFoirAccess}. */
+    access: FoirAccess | null;
+    accessStatus: FoirAccessStatus;
+    /** Ask the platform for the signed-in customer's access, again if it was read before. */
+    loadAccess(): Promise<void>;
+    /** The same, unless a read is already under way: then that one is awaited. */
+    ensureAccess(): Promise<void>;
     /** The API config; exposed so advanced consumers can call `@foir/sdk/auth` directly. */
     env: FoirEnv;
     /** The session store backing this provider. */
@@ -89,6 +101,33 @@ export interface FoirSession {
 export declare function useFoirSession(): FoirSession;
 /** The signed-in customer (`{ id, email }`), or null. */
 export declare function useFoirUser(): FoirCustomer | null;
+/** What {@link useFoirAccess} returns. */
+export interface FoirAccessState {
+    /**
+     * `loading` until the platform has answered for this session, `ready` once it
+     * has (and at once when nobody is signed in), `unavailable` when it could not
+     * be asked.
+     */
+    status: 'loading' | 'ready' | 'unavailable';
+    isLoading: boolean;
+    /** The signed-in customer's access, or null: signed out, loading or unavailable. */
+    access: FoirAccess | null;
+    /** Whether the customer holds the role with this key. False until known. */
+    hasRole(key: string): boolean;
+    /** Whether the customer's scopes cover this one. False until known. */
+    hasScope(scope: string): boolean;
+    /** Ask the platform again, for a role given or taken away since. */
+    reload(): Promise<void>;
+}
+/**
+ * The roles the signed-in customer holds and the scopes they resolve to, as the
+ * platform resolved them. Read on first use, again when the session refreshes,
+ * and whenever `reload` is called.
+ *
+ * Use it to decide what to show. It protects nothing: the platform checks every
+ * request whatever the page offers.
+ */
+export declare function useFoirAccess(): FoirAccessState;
 /** The sign-in / sign-out actions. */
 export declare function useFoirAuth(): {
     signIn: (vars: {

package/dist/react/feedback-notes.d.ts

@@ -45,7 +45,7 @@ export interface FoirFeedbackClient {
  *
  * The distinction earns its place because the three have different audiences.
  * `signIn` is the visitor's to fix. `scope` is the OPERATOR's — a role that does
- * not grant `notes:write` produces `missing required scope: notes:write`, which
+ * not grant `notes:create` produces `missing required scope: notes:create`, which
  * reads like a bad API key and is not one; the key is fine and the customer's
  * role is short a capability. `other` is everything the widget will not pretend
  * to understand.

package/dist/react/index.d.ts

@@ -2,7 +2,8 @@
  * `@foir/sdk/react` — drop-in React components for Foir customers.
  *
  * Wrap your app in `<FoirProvider>`, then read the session with
- * `useFoirSession` / `useFoirUser` and drive it with `useFoirAuth` — or drop in
+ * `useFoirSession` / `useFoirUser`, ask what the customer may see with
+ * `useFoirAccess`, and drive it with `useFoirAuth` — or drop in
  * the `<SignIn>`, `<OAuthButtons>`, and `<UserButton>` components. Built entirely
  * on `@foir/sdk/auth`; `react` is the only peer dependency.
  *
@@ -10,8 +11,8 @@
  * RECORD the page was rendered from rather than to its URL. It takes the data
  * client from `@foir/sdk/data` and the subject registry you built for it.
  */
-export { FoirProvider, useFoirSession, useFoirUser, useFoirAuth, } from './FoirProvider';
-export type { FoirProviderProps, FoirContextValue, FoirSession, FoirStatus, } from './FoirProvider';
+export { FoirProvider, useFoirSession, useFoirUser, useFoirAuth, useFoirAccess, } from './FoirProvider';
+export type { FoirProviderProps, FoirContextValue, FoirSession, FoirStatus, FoirAccessState, FoirAccessStatus, } from './FoirProvider';
 export { SignIn } from './SignIn';
 export type { SignInProps } from './SignIn';
 export { OAuthButtons } from './OAuthButtons';
@@ -21,5 +22,5 @@ export type { UserButtonProps } from './UserButton';
 export { FoirFeedback } from './FoirFeedback';
 export type { FoirFeedbackProps, FoirFeedbackClient } from './FoirFeedback';
 export { createLocalStorageAdapter } from './localStorageAdapter';
-export type { FoirCustomer, SessionAdapter, AuthProviderPublic } from '../auth';
+export type { FoirAccess, FoirCustomer, SessionAdapter, AuthProviderPublic } from '../auth';
 export type { FoirEnv } from '../graphql/foir-request';