@microteia/console 2.29.1 → 2.31.1

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,32 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.31.1] — 2026-10-26
+
+- docs(kernel/manifest): the optional prerequisite `portal-identity-signing` now names a third feature that signs with the functions' runtime account: a portal screen declaring `documentLinks` hands guests V4 signed URLs, and without `iam.serviceAccounts.signBlob` the guest cannot open its documents (the denial shows in the log of `getPortalDocumentUrl`). `microteia grant-signing` grants the same permission for all three.
+
+#### [2.31.0] — 2026-10-26
+
+- feat(grant-signing): new command. Portal sign-in through an identity provider and member two-step verification open sessions with `createCustomToken`, which needs the functions' runtime account to sign (`iam.serviceAccounts.signBlob`). `microteia grant-signing` reads the account the functions actually run as (`gcloud functions describe secondFactor`; the default compute account only when that function is not deployed), checks whether `iamcredentials.googleapis.com` is enabled and whether the account holds `roles/iam.serviceAccountTokenCreator` on itself without a condition, prints the missing `gcloud` steps, asks before running them, and reads the state again afterwards. `--check` only reads; `--yes` skips the question; without a terminal and without `--yes` it refuses. A permission error names the roles needed and hands over the commands.
+- feat(deploy): after the functions, a read-only check of session signing; when it is missing, a warning that points to `microteia grant-signing`. It never fails the deploy, and is skipped with a note when `gcloud` cannot answer.
+- docs(installation): the command table of `MICROTEIA.md` lists `grant-signing`.
+
+#### [2.30.3] — 2026-10-26
+
+- docs(kernel/manifest): the optional prerequisite `portal-identity-signing` now covers member two-step verification too — both open sessions minted with `createCustomToken`, and both fail at sign-in with `iam.serviceAccounts.signBlob` denied when the runtime account cannot sign. New optional prerequisite `self-service-tenants`: `SELF_SERVICE_TENANTS=false` in `.env.<projectId>` plus `microteia provision` stops sign-up from opening an organization in a shared installation; only SYSTEM opens organizations afterwards, and SYSTEM accounts should be protected by a sign-in provider with its own second factor. The kernel's declared optional backend parameters are now `AUDIT_ARCHIVE_BUCKET` and `SELF_SERVICE_TENANTS`.
+
+#### [2.30.2] — 2026-10-26
+
+- docs(kernel/manifest): new optional manual prerequisite `audit-archive-bucket`. An organization that keeps its audit trail as evidence turns on the daily archive with hash chain, which needs a bucket of its own with locked retention (`--enable-per-object-retention --retention-period=…`, then `--lock-retention-period`), `roles/storage.admin` on that bucket for the functions' runtime account, and `AUDIT_ARCHIVE_BUCKET` in `.env.<projectId>` followed by `microteia provision`. The step states the threat model: what a locked bucket prevents, what the chain only detects, and what a project owner can still do.
+
+#### [2.30.1] — 2026-10-26
+
+- docs(kernel/manifest): new optional manual prerequisite `portal-identity-signing`. An organization that signs portal guests in through an OpenID Connect provider needs the functions' runtime service account to sign sessions (`createCustomToken` → `iam.serviceAccounts.signBlob`): the IAM Service Account Credentials API enabled and the Service Account Token Creator role granted to that account on itself. Without it the provider confirms the guest and `completePortalSignIn` still fails; the step names the two `gcloud` commands. E-mail-link sign-in does not need it.
+
+#### [2.30.0] — 2026-10-23
+
+- feat(export-catalog): each installed extension now carries `documentTemplates` — every `document.template` it declares as a contract (`key`, `source`, and each parameter's `key`, `type`, `required`, `list`, `entityType`), never the template text, labels or sample. The authoring tools check a `render-document` step of another extension against it, so a misspelled `param.<key>` or a `belongsTo` that is not a single-record parameter is refused by `check` instead of reaching the office as a blank field. Always written, even empty; a snapshot taken by an older Console is read as "templates unknown".
+
 #### [2.29.1] — 2026-10-19
 
 - feat(vendor): `portal-example` joins the examples that travel to `extensions/examples/` — two screens with `portal` declared, guest-created records and a `portalView` written against `@microteia/portal`.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.29.1
+# Microteia Console 2.31.1
 
 Installs and updates Microteia in a Firebase project you own. It has no npm dependencies of its own —
 what it needs are command-line tools that are already on the machine, listed at the bottom.

package/lib/console/deploy.js

@@ -10,6 +10,7 @@ import { clearRegionOrphans, listDeployedFunctions } from './regionOrphans.js';
 import { gateProblemsFor } from './functionGate.js';
 import { deployFunctionsThatChanged } from './functionsUpToDate.js';
 import { checkCallables, invokerGrantCommand } from './callableAccess.js';
+import { checkSessionSigning, gcloudCapture } from './sessionSigning.js';
 import { checkHostingServed, htmlIsRevalidated } from './hostingCheck.js';
 import { provisionBackend } from './provision.js';
 import { installPath, readInstalledManifest } from './unpack.js';
@@ -233,6 +234,23 @@ export const deploy = async (args) => {
                     success(`all ${checks.length} callables answer calls from ${origin}`);
                 }
             }
+            // Só CONFERE: conceder é mudar permissão no projeto do escritório, e isso é um comando à parte, que
+            // diz o que vai mudar e pergunta. A falta não reprova o deploy — só quem usa entrada por provedor
+            // no portal ou verificação em duas etapas precisa dela —, mas é dita aqui, e não na primeira pessoa
+            // que tentar entrar.
+            try {
+                const signing = await checkSessionSigning(projectId, region, gcloudCapture);
+                if (signing.apiEnabled === false || signing.granted === false) {
+                    warn(`the functions' account (${signing.account}) cannot sign sessions yet. Portal sign-in through`);
+                    warn('  an identity provider and two-step verification need it. Run: microteia grant-signing');
+                }
+                else if (signing.apiEnabled === true && signing.granted === true) {
+                    success('the functions can sign sessions');
+                }
+            }
+            catch {
+                info('  could not check whether the functions can sign sessions — run "microteia grant-signing --check"');
+            }
             continue;
         }
         step(current, total, 'Hosting');

package/lib/console/exportCatalog.d.ts

@@ -112,6 +112,26 @@ export interface CatalogExtensionNavGroup {
     translations: Record<string, string>;
     order: number;
 }
+/**
+ * Um modelo de documento que a extensão declara (`document.template`), como CONTRATO: a chave, a origem
+ * e a forma de cada parâmetro. Viaja porque outra extensão GERA esse modelo pelo passo
+ * `render-document`, com `param.<chave>` e `belongsTo`, e um nome trocado ali só aparece na geração —
+ * com o campo em branco, ou com a recusa no clique.
+ *
+ * O que NÃO viaja é o texto do modelo, o rótulo, a regra e a amostra: é conteúdo, e o passo não os lê.
+ */
+export interface CatalogExtensionDocumentParameter {
+    key: string;
+    type: string;
+    required?: boolean;
+    list?: boolean;
+    entityType?: string;
+}
+export interface CatalogExtensionDocumentTemplate {
+    key: string;
+    source: 'record' | 'payload';
+    parameters: CatalogExtensionDocumentParameter[];
+}
 export interface CatalogExtensionExport {
     id: string;
     name: string;
@@ -124,6 +144,8 @@ export interface CatalogExtensionExport {
     exports: CatalogExtensionExportedArtifact[];
     /** Sempre escrita, mesmo vazia, pela mesma razão de `exports`. */
     navGroups: CatalogExtensionNavGroup[];
+    /** Sempre escrita, mesmo vazia, pela mesma razão de `exports`. */
+    documentTemplates: CatalogExtensionDocumentTemplate[];
 }
 export interface CatalogExport {
     version: number;

package/lib/console/exportCatalog.js

@@ -126,6 +126,45 @@ const navGroupsOf = (extension) => {
             }];
     });
 };
+const DOCUMENT_TEMPLATE_POINT = 'document.template';
+const documentParameterOf = (raw) => {
+    const record = asRecord(raw);
+    const key = text(record?.key);
+    const type = text(record?.type);
+    if (record === undefined || key === undefined || type === undefined)
+        return [];
+    const entityType = text(record.entityType);
+    return [{
+            key,
+            type,
+            ...(record.required === true ? { required: true } : {}),
+            ...(record.list === true ? { list: true } : {}),
+            ...(entityType === undefined ? {} : { entityType }),
+        }];
+};
+/**
+ * Os modelos de documento de uma cópia instalada, como contrato. É a mesma leitura que
+ * `documentTemplateContractOf` faz no kernel, repetida porque o Console não alcança `src/` — e é o
+ * teste que atravessa a fronteira que confere as duas.
+ */
+const documentTemplatesOf = (extension) => {
+    const contributes = Array.isArray(extension.manifest?.contributes) ? extension.manifest.contributes : [];
+    return contributes
+        .map(asRecord)
+        .filter((one) => one?.point === DOCUMENT_TEMPLATE_POINT)
+        .flatMap((one) => {
+        const metadata = asRecord(one.metadata);
+        const key = text(metadata?.key);
+        if (metadata === undefined || key === undefined)
+            return [];
+        return [{
+                key,
+                source: metadata.source === 'payload' ? 'payload' : 'record',
+                parameters: (Array.isArray(metadata.parameters) ? metadata.parameters : []).flatMap(documentParameterOf),
+            }];
+    })
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+};
 /**
  * A mesma dedução que a aplicação faz ao ler a tela (`screenDefinitionMapper.ts`): o `origin` gravado
  * quando ele existe, senão `plugin` para quem tem dono e `design` para o que o escritório criou. Ela é
@@ -223,6 +262,7 @@ export const buildCatalogExport = (input) => ({
         active: one.active,
         exports: exportedArtifacts(one),
         navGroups: navGroupsOf(one),
+        documentTemplates: documentTemplatesOf(one),
     }))
         .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
     screens: input.screens
@@ -344,6 +384,8 @@ export const exportCatalog = async (args) => {
     info(`  ${exported} artifact(s) are declared for other extensions to reference as <extension-id>/<id>.`);
     const groups = document.extensions.reduce((total, one) => total + one.navGroups.length, 0);
     info(`  ${groups} sidebar group(s) are declared, by key, for other extensions to join.`);
+    const templates = document.extensions.reduce((total, one) => total + one.documentTemplates.length, 0);
+    info(`  ${templates} document template(s) are declared, with the shape of their parameters, for other extensions to generate.`);
     blank();
     await checkIgnored(directory);
     info('It is a SNAPSHOT, and it says so: the authoring tools report when it was taken and warn when it');

package/lib/console/sessionSigning.d.ts

@@ -0,0 +1,64 @@
+import type { ParsedArgs } from '../shared/args.js';
+import type { CaptureResult } from '../shared/run.js';
+/**
+ * A permissão de ASSINAR sessões — a que `createCustomToken` usa. Duas features abrem sessão pelo servidor:
+ * a entrada do portal por provedor de identidade e a verificação em duas etapas dos membros. Sem a
+ * permissão, o provedor confirma a pessoa ou o código confere, e a entrada falha mesmo assim, com
+ * `iam.serviceAccounts.signBlob` negado no log da function.
+ *
+ * São duas coisas no projeto do escritório: a API IAM Service Account Credentials habilitada, e o papel
+ * Service Account Token Creator concedido à conta das functions SOBRE ELA MESMA.
+ *
+ * O Console não as faz sozinho no `deploy`: é alteração de permissão no projeto de outra pessoa, e
+ * acontece num comando que diz o que vai mudar e pergunta antes. O `deploy` só CONFERE, e sugere este.
+ */
+export declare const IAM_CREDENTIALS_API = "iamcredentials.googleapis.com";
+export declare const TOKEN_CREATOR_ROLE = "roles/iam.serviceAccountTokenCreator";
+/**
+ * A function cuja conta se lê. Uma do kernel que de fato assina — se ela roda com uma conta própria, é
+ * essa que precisa da permissão, e escrever de cor a conta padrão do Compute erraria em silêncio.
+ */
+export declare const SIGNING_FUNCTION = "secondFactor";
+export type Gcloud = (args: string[]) => Promise<CaptureResult>;
+export type AccountSource = 'function' | 'default';
+export interface SigningCheck {
+    account: string;
+    source: AccountSource;
+    /** `null` quando não deu para saber — permissão de leitura faltando, `gcloud` ausente. */
+    apiEnabled: boolean | null;
+    granted: boolean | null;
+}
+/** A conta padrão das functions de 2ª geração quando nenhuma foi configurada. */
+export declare const defaultComputeAccount: (projectNumber: string) => string;
+/**
+ * A conta que a function usa, no JSON do `gcloud functions describe`. A 2ª geração a põe em
+ * `serviceConfig`; a 1ª, na raiz. Vazio é "não sei", e não "a padrão": a padrão é decidida por quem chama.
+ */
+export declare const serviceAccountFromDescribe: (json: string) => string | null;
+/** A política IAM da conta concede a ela mesma criar token? */
+export declare const policyGrantsSelfSigning: (json: string, account: string) => boolean;
+export declare const enableApiArgs: (projectId: string) => string[];
+export declare const grantArgs: (projectId: string, account: string) => string[];
+export declare const gcloudLine: (args: string[]) => string;
+/**
+ * A conta que as functions usam: lida da function publicada e, só se não houver uma, a padrão do
+ * Compute a partir do número do projeto.
+ */
+export declare const resolveRuntimeAccount: (projectId: string, region: string, gcloud: Gcloud) => Promise<{
+    account: string;
+    source: AccountSource;
+}>;
+/** Só LÊ. É o que o `deploy` usa para avisar, e o que este comando usa antes e depois de mudar. */
+export declare const checkSessionSigning: (projectId: string, region: string, gcloud: Gcloud) => Promise<SigningCheck>;
+/** O que falta, como comandos — os que este comando roda, e os que se entregam a quem tem o papel. */
+export declare const missingSteps: (projectId: string, check: SigningCheck) => string[][];
+/** Nunca quebra quem chama: sem `gcloud`, o `spawn` falha, e a resposta é "não deu para ler". */
+export declare const gcloudCapture: Gcloud;
+/**
+ * `microteia grant-signing` — confere a permissão de assinar sessões e, com confirmação, a concede.
+ *
+ * `--check` só confere. `--yes` dispensa a pergunta (para quem roda num script, e sabe o que roda).
+ * Sem terminal e sem `--yes`, recusa: concordar por omissão com uma mudança de permissão é o que este
+ * comando existe para não fazer.
+ */
+export declare const grantSigning: (args: ParsedArgs) => Promise<void>;

package/lib/console/sessionSigning.js

@@ -0,0 +1,203 @@
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { hasFlag, requiredFlag } from '../shared/args.js';
+import { capture, run } from '../shared/run.js';
+import { blank, bullets, failure, heading, info, success, warn } from '../shared/ui.js';
+import { ENVIRONMENT_FILE, readEnvironment } from './environment.js';
+import { readInstalledManifest } from './unpack.js';
+/**
+ * A permissão de ASSINAR sessões — a que `createCustomToken` usa. Duas features abrem sessão pelo servidor:
+ * a entrada do portal por provedor de identidade e a verificação em duas etapas dos membros. Sem a
+ * permissão, o provedor confirma a pessoa ou o código confere, e a entrada falha mesmo assim, com
+ * `iam.serviceAccounts.signBlob` negado no log da function.
+ *
+ * São duas coisas no projeto do escritório: a API IAM Service Account Credentials habilitada, e o papel
+ * Service Account Token Creator concedido à conta das functions SOBRE ELA MESMA.
+ *
+ * O Console não as faz sozinho no `deploy`: é alteração de permissão no projeto de outra pessoa, e
+ * acontece num comando que diz o que vai mudar e pergunta antes. O `deploy` só CONFERE, e sugere este.
+ */
+export const IAM_CREDENTIALS_API = 'iamcredentials.googleapis.com';
+export const TOKEN_CREATOR_ROLE = 'roles/iam.serviceAccountTokenCreator';
+/**
+ * A function cuja conta se lê. Uma do kernel que de fato assina — se ela roda com uma conta própria, é
+ * essa que precisa da permissão, e escrever de cor a conta padrão do Compute erraria em silêncio.
+ */
+export const SIGNING_FUNCTION = 'secondFactor';
+const GCLOUD_BIN = 'gcloud';
+/** A conta padrão das functions de 2ª geração quando nenhuma foi configurada. */
+export const defaultComputeAccount = (projectNumber) => `${projectNumber}-compute@developer.gserviceaccount.com`;
+/**
+ * A conta que a function usa, no JSON do `gcloud functions describe`. A 2ª geração a põe em
+ * `serviceConfig`; a 1ª, na raiz. Vazio é "não sei", e não "a padrão": a padrão é decidida por quem chama.
+ */
+export const serviceAccountFromDescribe = (json) => {
+    try {
+        const parsed = JSON.parse(json);
+        const account = parsed.serviceConfig?.serviceAccountEmail ?? parsed.serviceAccountEmail;
+        return typeof account === 'string' && account.includes('@') ? account : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** A política IAM da conta concede a ela mesma criar token? */
+export const policyGrantsSelfSigning = (json, account) => {
+    const parsed = JSON.parse(json);
+    const member = `serviceAccount:${account}`;
+    return (parsed.bindings ?? []).some((binding) => binding.role === TOKEN_CREATOR_ROLE
+        && binding.condition === undefined
+        && Array.isArray(binding.members)
+        && binding.members.includes(member));
+};
+export const enableApiArgs = (projectId) => ['services', 'enable', IAM_CREDENTIALS_API, `--project=${projectId}`];
+export const grantArgs = (projectId, account) => [
+    'iam', 'service-accounts', 'add-iam-policy-binding', account,
+    `--member=serviceAccount:${account}`,
+    `--role=${TOKEN_CREATOR_ROLE}`,
+    `--project=${projectId}`,
+];
+export const gcloudLine = (args) => [GCLOUD_BIN, ...args].join(' ');
+/**
+ * A conta que as functions usam: lida da function publicada e, só se não houver uma, a padrão do
+ * Compute a partir do número do projeto.
+ */
+export const resolveRuntimeAccount = async (projectId, region, gcloud) => {
+    const described = await gcloud([
+        'functions', 'describe', SIGNING_FUNCTION, `--region=${region}`, `--project=${projectId}`, '--format=json',
+    ]);
+    const fromFunction = described.code === 0 ? serviceAccountFromDescribe(described.stdout) : null;
+    if (fromFunction)
+        return { account: fromFunction, source: 'function' };
+    const project = await gcloud(['projects', 'describe', projectId, '--format=value(projectNumber)']);
+    const projectNumber = project.stdout.trim();
+    if (project.code !== 0 || !/^\d+$/.test(projectNumber)) {
+        throw new Error(`Could not read the project number of ${projectId}.${project.stderr.trim() === '' ? '' : `\n  ${project.stderr.trim()}`}`);
+    }
+    return { account: defaultComputeAccount(projectNumber), source: 'default' };
+};
+/** Só LÊ. É o que o `deploy` usa para avisar, e o que este comando usa antes e depois de mudar. */
+export const checkSessionSigning = async (projectId, region, gcloud) => {
+    const { account, source } = await resolveRuntimeAccount(projectId, region, gcloud);
+    const services = await gcloud([
+        'services', 'list', '--enabled', `--project=${projectId}`,
+        `--filter=config.name=${IAM_CREDENTIALS_API}`, '--format=value(config.name)',
+    ]);
+    const apiEnabled = services.code === 0 ? services.stdout.trim() === IAM_CREDENTIALS_API : null;
+    const policy = await gcloud(['iam', 'service-accounts', 'get-iam-policy', account, `--project=${projectId}`, '--format=json']);
+    let granted = null;
+    if (policy.code === 0) {
+        try {
+            granted = policyGrantsSelfSigning(policy.stdout, account);
+        }
+        catch {
+            granted = null;
+        }
+    }
+    return { account, source, apiEnabled, granted };
+};
+/** O que falta, como comandos — os que este comando roda, e os que se entregam a quem tem o papel. */
+export const missingSteps = (projectId, check) => [
+    ...(check.apiEnabled === true ? [] : [enableApiArgs(projectId)]),
+    ...(check.granted === true ? [] : [grantArgs(projectId, check.account)]),
+];
+/** Nunca quebra quem chama: sem `gcloud`, o `spawn` falha, e a resposta é "não deu para ler". */
+export const gcloudCapture = (args) => capture(GCLOUD_BIN, args).catch((error) => ({
+    code: -1,
+    stdout: '',
+    stderr: error instanceof Error ? error.message : String(error),
+}));
+const isPermissionError = (error) => error instanceof Error && /PERMISSION_DENIED|403|does not have .*permission|setIamPolicy/i.test(error.message);
+const confirm = async (question) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^(y|yes)$/i.test((await rl.question(`${question} [y/N] `)).trim());
+    }
+    finally {
+        rl.close();
+    }
+};
+const regionOf = async (root, recorded) => {
+    try {
+        return (await readInstalledManifest(root)).requires.functionsRegion;
+    }
+    catch {
+        return recorded;
+    }
+};
+/**
+ * `microteia grant-signing` — confere a permissão de assinar sessões e, com confirmação, a concede.
+ *
+ * `--check` só confere. `--yes` dispensa a pergunta (para quem roda num script, e sabe o que roda).
+ * Sem terminal e sem `--yes`, recusa: concordar por omissão com uma mudança de permissão é o que este
+ * comando existe para não fazer.
+ */
+export const grantSigning = async (args) => {
+    const file = resolve(hasFlag(args, 'file') ? requiredFlag(args, 'file') : join(process.cwd(), ENVIRONMENT_FILE));
+    const root = dirname(file);
+    const environment = await readEnvironment(file);
+    const projectId = environment.firebase.projectId;
+    if (projectId === null) {
+        throw new Error('This installation is not connected yet. Run "microteia connect --project <id>".');
+    }
+    const region = await regionOf(root, environment.firebase.region);
+    heading(`Session signing in ${projectId}`);
+    info('Signing in to the portal with an identity provider, and confirming the code of two-step');
+    info('verification, open a session the server signs. The functions\' account must be allowed to do it.');
+    blank();
+    const before = await checkSessionSigning(projectId, region, gcloudCapture);
+    info(`  account: ${before.account}`);
+    info(before.source === 'function'
+        ? `  (read from the deployed function ${SIGNING_FUNCTION})`
+        : `  (the default compute account — ${SIGNING_FUNCTION} is not deployed yet, or could not be read)`);
+    const state = (value) => (value === null ? 'could not be read' : value ? 'yes' : 'no');
+    info(`  ${IAM_CREDENTIALS_API} enabled: ${state(before.apiEnabled)}`);
+    info(`  ${TOKEN_CREATOR_ROLE} on itself: ${state(before.granted)}`);
+    blank();
+    const steps = missingSteps(projectId, before);
+    if (steps.length === 0) {
+        success('the functions can sign sessions — nothing to change');
+        return;
+    }
+    info(hasFlag(args, 'check') ? 'To grant it, run "microteia grant-signing", or:' : 'This will run:');
+    bullets(steps.map(gcloudLine));
+    if (before.apiEnabled === null || before.granted === null) {
+        warn('part of the current state could not be read; running a step that is already done changes nothing.');
+    }
+    if (hasFlag(args, 'check'))
+        return;
+    blank();
+    if (!hasFlag(args, 'yes')) {
+        if (!process.stdin.isTTY) {
+            throw new Error('Not running in a terminal. Re-run with --yes to apply, or run the commands above.');
+        }
+        if (!(await confirm('Apply these changes?'))) {
+            info('Nothing was changed.');
+            return;
+        }
+    }
+    try {
+        for (const step of steps)
+            await run(GCLOUD_BIN, step);
+    }
+    catch (error) {
+        if (!isPermissionError(error))
+            throw error;
+        blank();
+        failure('the account signed in to gcloud may not change permissions in this project.');
+        info('  It needs Owner, or Service Account Admin plus Service Usage Admin. Ask someone who has them');
+        info('  to run:');
+        bullets(steps.map(gcloudLine));
+        throw new Error('Session signing was not granted.', { cause: error });
+    }
+    // IAM é eventualmente consistente: a releitura logo depois pode não refletir a concessão ainda.
+    const after = await checkSessionSigning(projectId, region, gcloudCapture);
+    blank();
+    if (after.apiEnabled !== false && after.granted !== false) {
+        success('the functions can sign sessions');
+    }
+    else {
+        warn('the change was accepted but does not show yet — IAM can take a minute. Check again with');
+        warn('  microteia grant-signing --check');
+    }
+};

package/lib/index.js

@@ -11,6 +11,7 @@ import { unpack } from './console/unpack.js';
 import { deploy } from './console/deploy.js';
 import { provision } from './console/provision.js';
 import { exportCatalog } from './console/exportCatalog.js';
+import { grantSigning } from './console/sessionSigning.js';
 import { pluginInit } from './console/pluginWorkspace.js';
 import { versionReport } from './console/versions.js';
 import { newerThan } from './console/channel.js';
@@ -50,6 +51,13 @@ const COMMANDS = [
         audience: 'office',
         execute: provision,
     },
+    {
+        name: 'grant-signing',
+        usage: 'microteia grant-signing [--check] [--yes]',
+        summary: 'Let the functions sign sessions (portal identity providers, two-step verification).',
+        audience: 'office',
+        execute: grantSigning,
+    },
     {
         name: 'export-catalog',
         usage: 'microteia export-catalog --tenant <tenantId> [--output <path>]',

package/lib/kernel/manifest.js

@@ -91,6 +91,70 @@ export const MANUAL_PREREQUISITES = [
             + 'with the credential it was given and refuses everything else.',
         optional: true,
     },
+    {
+        id: 'portal-identity-signing',
+        title: 'Let the functions sign, if an organization signs portal guests in with an identity provider, requires two-step verification or gives guests short-lived document links',
+        detail: 'Two features open a session the server mints with createCustomToken, which signs with the service '
+            + 'account the functions run as: a portal guest who signs in through an OpenID Connect provider '
+            + 'configured in Settings > Portal > Sign-in, and a member who confirms the code of two-step '
+            + 'verification (Organization > Security) — the session that carries the proof. Without the '
+            + 'permission the provider confirms the guest, or the code is right, and entering still fails, with '
+            + '"iam.serviceAccounts.signBlob" denied in the log of completePortalSignIn or secondFactor. An '
+            + 'organization cannot lock itself out by turning two-step verification on before this is done: '
+            + 'saving a rule that reaches the person saving it requires that person to have proved the code in '
+            + 'that session, which already needs the signature. A third feature signs with the same account: a '
+            + 'portal screen that declares documentLinks hands guests signed links that expire in minutes, and '
+            + 'without the permission the guest cannot open its documents ("signBlob" denied in the log of '
+            + 'getPortalDocumentUrl). With Console 2.31.0 or newer, run microteia '
+            + 'grant-signing: it reads the account the functions actually run as, shows what it would change and '
+            + 'asks before changing it (--check only reads), and microteia deploy reports when it is missing. By '
+            + 'hand: enable the IAM Service Account Credentials API '
+            + '(gcloud services enable iamcredentials.googleapis.com --project=<projectId>) and grant the '
+            + 'runtime service account the Service Account Token Creator role on itself: gcloud iam '
+            + 'service-accounts add-iam-policy-binding <projectNumber>-compute@developer.gserviceaccount.com '
+            + '--member=serviceAccount:<projectNumber>-compute@developer.gserviceaccount.com '
+            + '--role=roles/iam.serviceAccountTokenCreator --project=<projectId>. Signing in by e-mail link '
+            + 'does not need it.',
+        optional: true,
+    },
+    {
+        id: 'audit-archive-bucket',
+        title: 'Create a bucket with locked retention, if an organization must keep its audit trail as evidence',
+        detail: 'The audit trail stays available for 30 days unless an organization raises it, and an organization '
+            + 'can also turn on a daily archive with a hash chain (Audit trail > Retention and archive). The archive '
+            + 'needs a bucket of its own, never the default one: gcloud storage buckets create '
+            + 'gs://<bucket> --project=<projectId> --location=<region> --uniform-bucket-level-access '
+            + '--enable-per-object-retention --retention-period=5y, then gcloud storage buckets update gs://<bucket> '
+            + '--lock-retention-period (irreversible: from then on nobody, project owners included, can delete or '
+            + 'overwrite an archived day before it is five years old, or shorten the period). Use the longest '
+            + 'period any organization here is legally bound to; each organization can lock its own days for '
+            + 'longer. Grant the functions\' runtime service account roles/storage.admin on THAT bucket only (it '
+            + 'reads the bucket\'s retention settings and sets each day\'s retention, which the object roles '
+            + 'do not cover), write AUDIT_ARCHIVE_BUCKET=<bucket> in .env.<projectId> '
+            + 'and run microteia provision. What it protects against, and what it does not: a locked bucket stops '
+            + 'deletion and rewriting of what was already archived; the chain makes any change visible on '
+            + 'verification. A project owner can still alter or delete an audit line in Firestore BEFORE its day '
+            + 'is exported (the export runs hourly, about an hour after midnight UTC), turn the archive off (that '
+            + 'itself is a CRITICAL audit entry, and the gap shows in the chain), or delete the whole project. '
+            + 'Against a rewrite of an unlocked bucket, only the last day\'s hash kept OUTSIDE the project proves '
+            + 'anything — the organization can copy it from the archive screen. Without this setting nothing '
+            + 'changes for anyone.',
+        optional: true,
+    },
+    {
+        id: 'self-service-tenants',
+        title: 'Stop sign-up from opening an organization, if this installation is shared',
+        detail: 'By default every new account gets an organization of its own, with that person as the owner. In an '
+            + 'installation shared by several organizations — each one created on purpose — that lets anyone who '
+            + 'can create an account open one. Write SELF_SERVICE_TENANTS=false in .env.<projectId> and run '
+            + 'microteia provision: from then on a new account waits to be added to an organization, and only the '
+            + 'installation administrator (SYSTEM) opens organizations, in Access management > Organizations, '
+            + 'naming an owner who already has an account. The first account of the installation gets one '
+            + 'anyway. Any value other than empty, true or false is read as false. Two-step verification is '
+            + 'required per organization and does not reach the installation administrator: protect SYSTEM '
+            + 'accounts with a sign-in provider that enforces its own second factor.',
+        optional: true,
+    },
 ];
 /**
  * Os nomes das Cloud Functions saem de `functions/src/index.ts`, a mesma fonte e o mesmo parse que

package/lib/shared/paths.d.ts

@@ -87,4 +87,4 @@ export declare const consoleRoot: string;
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export declare const CLI_VERSION = "2.29.1";
+export declare const CLI_VERSION = "2.31.1";

package/lib/shared/paths.js

@@ -94,4 +94,4 @@ export const consoleRoot = resolve(here, '..', '..');
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export const CLI_VERSION = '2.29.1';
+export const CLI_VERSION = '2.31.1';

package/lib/vendor/installationDocs.js

@@ -93,6 +93,7 @@ const commandRows = () => [
     '| `microteia deploy [--only …] [--prune] [--all]` | Publishes what is in place: `rules`, `indexes`, `functions`, `hosting`. A Cloud Function the project already runs with this exact code is not deployed again; `--all` deploys every one of them anyway. `--prune` also deletes functions left behind in a region this version no longer uses |',
     '| `microteia provision [--prune] [--all]` | Gives installed extensions the functions and indexes they ask for |',
     '| `microteia connect --project <id>` | Binds this installation to a Firebase project you own |',
+    '| `microteia grant-signing [--check] [--yes]` | Lets the functions sign sessions — needed by portal sign-in through an identity provider and by two-step verification. Reads the account the functions run as, shows what it would change, and asks before enabling the IAM Service Account Credentials API and granting the account Service Account Token Creator on itself. `--check` only reads |',
     '| `microteia plugin-init` | Prepares `extensions/` for authoring in TypeScript |',
     '| `microteia export-catalog --tenant <id>` | Writes what an office has — screens, lists, installed extensions — into `extensions/`, so the authoring tools can see it. Reads only; with no `--tenant` it lists the offices. The file is a snapshot and is git-ignored: it carries names the office typed |',
 ].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microteia/console",
-  "version": "2.29.1",
+  "version": "2.31.1",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "UNLICENSED",
   "type": "module",