@foir/sdk 0.19.0 → 0.20.0

package/dist/auth/ops.d.ts

@@ -44,6 +44,7 @@ export declare const AUTH_OPS: {
     readonly customerSignupContext: "customerSignupContext";
     readonly currentUser: "currentUser";
     readonly myProviderToken: "myProviderToken";
+    readonly whoami: "whoami";
     readonly customerLogin: "customerLogin";
     readonly customerRegister: "customerRegister";
     readonly customerRequestOTP: "customerRequestOTP";

package/dist/auth.js

@@ -679,7 +679,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 = {};
@@ -1034,6 +1034,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",
@@ -1357,6 +1360,264 @@ async function requireAdmin(adapter, options) {
   return user;
 }
 
+// src/auth/grant-table.generated.ts
+var GRANT_TABLE = [
+  ["records:read", true, ["own", "named", "all"], []],
+  ["records:create", true, [], []],
+  ["records:write", true, ["own", "named", "all"], []],
+  ["records:delete", true, ["own", "named", "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, [], []],
+  ["notes:write", false, [], []],
+  ["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", "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"]],
+  ["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", "audit:read", "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;
+}
+var FoirAccessDeniedError = class extends Error {
+  code = "FOIR_ACCESS_DENIED";
+  reason;
+  /** The role that was required, when one was. */
+  role;
+  /** The scope that was required, when one was. */
+  scope;
+  constructor(reason, required) {
+    super(denialMessage(reason, required));
+    this.name = "FoirAccessDeniedError";
+    this.reason = reason;
+    this.role = required.role;
+    this.scope = required.scope;
+  }
+};
+function denialMessage(reason, required) {
+  switch (reason) {
+    case "signed_out":
+      return "[foir] nobody is signed in";
+    case "role_not_held":
+      return `[foir] the signed-in customer does not hold the role "${required.role}"`;
+    case "roles_unknown":
+      return `[foir] the platform did not say which roles the signed-in customer holds, so "${required.role}" could not be checked`;
+    case "scope_not_held":
+      return `[foir] the signed-in customer's scopes do not cover "${required.scope}"`;
+  }
+}
+async function requireRole(adapter, env, key) {
+  const access = await getSessionAccess(adapter, env);
+  if (!access) throw new FoirAccessDeniedError("signed_out", { role: key });
+  if (access.roles === null) throw new FoirAccessDeniedError("roles_unknown", { role: key });
+  if (!access.roles.includes(key)) throw new FoirAccessDeniedError("role_not_held", { role: key });
+  return access;
+}
+async function requireScope(adapter, env, scope) {
+  const access = await getSessionAccess(adapter, env);
+  if (!access) throw new FoirAccessDeniedError("signed_out", { scope });
+  if (!holds(access.scopes, scope)) throw new FoirAccessDeniedError("scope_not_held", { scope });
+  return access;
+}
+
 // src/auth/hosted.ts
 var DEFAULT_COOKIE_NAME = "foir_customer_session";
 var DEFAULT_SESSION_PATH = "/session/token";
@@ -1567,6 +1828,7 @@ function trimSlash(s) {
 }
 export {
   AUTH_OPS,
+  FoirAccessDeniedError,
   FoirAuthDowngradedError,
   FoirSessionExpiredError,
   authedOp,
@@ -1574,6 +1836,7 @@ export {
   clearSession,
   createFoirSessionClient,
   currentUser,
+  customerAccess,
   customerJoinWaitlist,
   customerLogin,
   customerLoginOTP,
@@ -1594,8 +1857,11 @@ export {
   getAuthConfig,
   getAuthProviders,
   getDefaultAuthProvider,
+  getSessionAccess,
   getSessionCustomer,
   getSessionToken,
+  hasRole,
+  hasScope,
   hostedLoginUrl,
   hostedLogoutUrl,
   loginWithOTP,
@@ -1608,6 +1874,8 @@ export {
   registerWithPassword,
   requireAdmin,
   requireAuth,
+  requireRole,
+  requireScope,
   resetPasswordAndSignIn,
   saveSession,
   selectOrganization,

package/dist/data/builtins.d.ts

@@ -520,7 +520,7 @@ export interface FoirCustomerNote {
  * What a note surface has to know about the project before it renders anything
  * — `foir.ns.notes.noteConfig`.
  *
- * Charged `notes:write` rather than `notes:read`, and refused to a caller with
+ * Charged `notes:create` rather than `notes:read`, and refused to a caller with
  * no customer session, because the only caller it is useful to is one that can
  * submit. So a composer can read it as its single readiness probe: an answer
  * means this visitor may write, and a refusal names which half is missing.
@@ -551,7 +551,54 @@ export interface FoirMyNotesArgs {
  * internal ones.
  */
 export type FoirMyNotesResult = FoirConnection<FoirCustomerNote>;
-/** `createMyNote` arguments. */
+/**
+ * `writeNote` arguments: the one note create, for a signed-in customer and for
+ * a visitor alike. It asks `notes:create` of both.
+ *
+ * A signed-in customer's note is theirs and comes back in `myNotes`. A
+ * visitor's, through a key that gives `notes:create` to whoever comes through
+ * it, on a project that takes visitors' notes, is nobody's: ask for its `id`
+ * and `createdAt` and nothing else, because nothing reads it back.
+ *
+ * Served by a data API that has the field. `<FoirFeedback>` still writes
+ * through `createMyNote`, the same create under its older name, which every
+ * data API serves.
+ */
+export interface FoirWriteNoteArgs {
+    /** A visitor may write about a record and nothing else. */
+    subjectType: FoirNoteSubjectType;
+    subjectId: string;
+    /** Required when `subjectType` is `'record'`, refused otherwise. */
+    subjectModelKey?: string;
+    body: string;
+    /** Reply within an existing thread. Refused where nobody is signed in. */
+    parentNoteId?: string;
+    /**
+     * Files to submit with this note, already uploaded through
+     * `createFileUpload` / `confirmFileUpload`. Refused where nobody is signed in.
+     *
+     * A file this caller cannot read is REFUSED and the note is not written. That
+     * is not a rough edge to code around: a create that accepted the note and
+     * dropped the attachment would leave the author believing they sent a
+     * screenshot nobody has.
+     */
+    attachmentFileIds?: string[];
+    /**
+     * Where the operators may reply to a visitor. Refused from a signed-in
+     * customer, whose note has an author.
+     *
+     * Captured as typed and NEVER verified: it is not treated as proof of who
+     * wrote the note, and nothing is sent to it to confirm it. Do not build a
+     * flow that assumes the address is reachable.
+     */
+    contactEmail?: string;
+}
+/**
+ * `createMyNote` arguments.
+ *
+ * @deprecated `createMyNote` is the older name of `writeNote` for a signed-in
+ * customer. Use `writeNote` and {@link FoirWriteNoteArgs}.
+ */
 export interface FoirCreateMyNoteArgs {
     subjectType: FoirNoteSubjectType;
     subjectId: string;
@@ -581,6 +628,10 @@ export interface FoirCreateMyNoteArgs {
  *
  * WRITE-ONLY. Nothing reads an anonymous note back on the public plane, which
  * is why the result is a receipt rather than the note.
+ *
+ * @deprecated `submitAnonymousNote` is the older name of `writeNote` for a
+ * visitor. Use `writeNote` and {@link FoirWriteNoteArgs}, asking for `id` and
+ * `createdAt`.
  */
 export interface FoirSubmitAnonymousNoteArgs {
     /**
@@ -606,7 +657,12 @@ export interface FoirSubmitAnonymousNoteArgs {
      */
     contactEmail?: string;
 }
-/** What `submitAnonymousNote` returns. */
+/**
+ * What `submitAnonymousNote` returns.
+ *
+ * @deprecated With the field it answers. `writeNote` answers a visitor with
+ * the note's `id` and `createdAt`.
+ */
 export interface FoirAnonymousNoteReceipt {
     /**
      * A reference for this submission, to quote when following it up.

package/dist/data/index.d.ts

@@ -59,7 +59,7 @@ export { planFoirModelCall, planFoirNamespaceCall } from './document';
 export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
 export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
 export type { FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
-export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirSubmitAnonymousNoteArgs, FoirAnonymousNoteReceipt, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirWriteNoteArgs, FoirSubmitAnonymousNoteArgs, FoirAnonymousNoteReceipt, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
 /**
  * Pre-rename spellings. The `<Name>Block` wrappers and the `<Name>Value`
  * split are the same thing as the types above — an item IS its value — so each

package/dist/data/transport.d.ts

@@ -155,10 +155,10 @@ export type FoirOperationGeneratedModule<S extends FoirSchemaDefinition = FoirSc
  * const foir = createFoirClient({ apiUrl, dispatch, generated });
  * ```
  *
- * The endpoint calls Foir AS the operation, with the capabilities the operation
+ * The endpoint calls Foir AS the operation, with the grants the operation
  * declared, and holds no key of its own. api-public accepts the token as a
  * caller in its own right: it builds the schema overlay from the token's
- * capabilities, and it reads the organization and the customer from the
+ * grants, and it reads the organization and the customer from the
  * token's claims. So nothing a key client configures beside its key
  * (`bearerToken`, `orgId`, `channel`) means anything here, and none of it is
  * accepted.

package/dist/next.js

@@ -921,6 +921,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/placement/index.d.ts

@@ -5,8 +5,9 @@
  * reaches a cross-site frame, so the console hands the page a short-lived token
  * instead, by message, to your placement's origin only. The token is the
  * operator looking at the page, acting through your app at the level your app
- * is installed at, carrying the scopes your placement declares that this
- * operator holds. Your page runs no login of its own.
+ * is installed at, carrying what your placement declares and this operator
+ * holds, as grants in the permission catalogue's names. Your page runs no
+ * login of its own.
  *
  * ```ts
  * import { connectPlacement, FOIR_CONSOLE_ORIGINS } from '@foir/sdk/placement';
@@ -15,7 +16,7 @@
  *   apiUrl: 'https://api.foir.dev',
  *   consoleOrigins: FOIR_CONSOLE_ORIGINS.production,
  * });
- * if (session.can('records:write:preorder')) showEditButtons();
+ * if (session.can('records:write.all:preorder')) showEditButtons();
  * const data = await session.request('{ preorders { items { id } } }');
  * ```
  *
@@ -52,14 +53,38 @@ export interface PlacementGrant {
     expiresAt: string;
     /** The organisation the page acts at: your app's install. Empty for the project. */
     orgId: string;
-    /** What the token carries. */
+    /**
+     * What the token carries: the grants your placement declares that this
+     * operator holds, in the permission catalogue's names. A grant the operator
+     * holds part of is carried as that part, so ask with `can` and not by
+     * looking for a spelling here.
+     */
+    grants: string[];
+    /** Each grant your placement declares that the token does not carry whole, and why. */
+    withheldGrants: {
+        grant: string;
+        reason: string;
+    }[];
+    /**
+     * @deprecated Read `grants`. The same list under the name it had before a
+     * placement declared grants.
+     */
     grantedScopes: string[];
-    /** What your placement declares that this operator does not hold, and why. */
+    /**
+     * @deprecated Read `withheldGrants`. The same list under the name it had
+     * before a placement declared grants.
+     */
     withheld: {
         scope: string;
         reason: string;
     }[];
 }
+/**
+ * What a console sends with a token. A console of the release before sends
+ * only `grantedScopes` and `withheld`, and the session reads `grants` from
+ * those.
+ */
+type PlacementGrantMessage = Pick<PlacementGrant, 'accessToken' | 'expiresAt' | 'orgId'> & Partial<Pick<PlacementGrant, 'grants' | 'withheldGrants' | 'grantedScopes' | 'withheld'>>;
 /** How the console looks, for an embedded page to match. */
 export interface PlacementAppearance {
     /**
@@ -71,7 +96,7 @@ export interface PlacementAppearance {
 /** A message the console sends an embedded page. */
 export type PlacementHostMessage = {
     type: typeof PLACEMENT_MESSAGE.token;
-    grant: PlacementGrant;
+    grant: PlacementGrantMessage;
 } | {
     type: typeof PLACEMENT_MESSAGE.refused;
     reason: string;
@@ -138,8 +163,14 @@ export interface PlacementSession {
      * older than this). Kept current as the operator changes it.
      */
     readonly appearance: PlacementAppearance | null;
-    /** Whether the token carries this scope, to hide or grey out what the operator cannot do. */
-    can(scope: string): boolean;
+    /**
+     * Whether the token covers this grant, to hide or grey out what the operator
+     * cannot do. It answers as Foir's API would: a grant for every model covers
+     * the same grant for one, and one for every owner's rows covers a person's
+     * own. `can('records:read.all:order')` is true for a token that carries
+     * `records:read.all`.
+     */
+    can(grant: string): boolean;
     /** A GraphQL request to Foir's API as the operator, through your app. */
     request<TResult = unknown>(document: string | {
         toString(): string;
@@ -156,3 +187,4 @@ export interface PlacementSession {
  * console gives no token, or when none arrives in time.
  */
 export declare function connectPlacement(options: ConnectPlacementOptions): Promise<PlacementSession>;
+export {};