firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/library-sharing.js

@@ -0,0 +1,220 @@
+/**
+ * Library reuse (Plan20 R10; root `native_library_sharing.py`,
+ * `native_library_dependents.py`, `native_library_parameters.py`).
+ *
+ * - Sharing is per exact immutable version, with workspaces of the same
+ *   organization only. An administrator of the owner workspace grants read or
+ *   read-and-use and revokes. A grant never lets the recipient edit or publish
+ *   the source, and never carries credentials.
+ * - Revoking stops future reads and new uses. It does not erase copies the
+ *   recipient already made (forks, bound copies) or roll back accepted work.
+ * - Binding fixes a parameterized version's declared values into a new private
+ *   immutable resource of this workspace. Values are typed scalars at declared
+ *   content fields: no interpolation, templates or code.
+ * - Dependents are this workspace's own world and scenario versions that
+ *   reference a version, never another recipient's.
+ * Definitions stay cloud-owned: nothing here writes or keeps a local body.
+ */
+import { api } from '../auth.js';
+import { CliError } from '../http.js';
+import { SHA256_HEX } from './contracts.js';
+import { libraryRow } from './cloud-resources.js';
+export const DEPENDENT_KINDS = ['world', 'scenario'];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RESPONSE_LIMIT = 4 * 1024 * 1024;
+const PAGE = 25;
+const PAGE_KEYS = 'count,next,page,page_size,previous,results';
+const GRANT_KEYS = 'allow_use,created_at,id,recipient_workspace_id,request_key,revision_id,revoked_at';
+const DEPENDENT_KEYS = 'created_at,digest,id,kind,name,revision,world_id';
+/** Root's bound on a string parameter value; the definition's own grammar may be stricter. */
+const STRING_MAX = 4000;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const uuid = (value) => typeof value === 'string' && UUID.test(value);
+const time = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const keys = (value) => Object.keys(value).sort().join(',');
+const unconfirmed = (what) => new CliError('native_response_unconfirmed', `The ${what} response could not be confirmed. Nothing further was sent for it.`);
+const scoped = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal, maximumResponseBytes: RESPONSE_LIMIT });
+const base = (scope) => `/api/workspaces/${scope.workspace}/native-library`;
+/** A UUID argument exactly as Firedrill printed it, lowercased. */
+export function libraryId(value, label) {
+    if (!uuid(value))
+        throw new CliError('arguments_invalid', `Use the ${label} exactly as Firedrill printed it. Nothing was sent.`, 2);
+    return value.toLowerCase();
+}
+function pageNumber(value) {
+    const page = value ?? 1;
+    if (!Number.isSafeInteger(page) || page < 1)
+        throw new CliError('arguments_invalid', 'Use --page with a positive page number.', 2);
+    return page;
+}
+/** Root's standard page envelope for the 25-row page that was asked for. */
+function pageOf(raw, page, row, what) {
+    if (!object(raw) || keys(raw) !== PAGE_KEYS || !Number.isSafeInteger(raw.count) || raw.count < 0 || raw.page !== page
+        || raw.page_size !== PAGE || (raw.next !== null && typeof raw.next !== 'string') || (raw.previous !== null && typeof raw.previous !== 'string')
+        || !Array.isArray(raw.results) || raw.results.length > PAGE || (raw.next !== null) !== (page * PAGE < raw.count))
+        throw unconfirmed(what);
+    return { count: raw.count, page, next: raw.next, previous: raw.previous, results: raw.results.map(row) };
+}
+function grantRow(revisionId) {
+    return (value) => {
+        if (!object(value) || keys(value) !== GRANT_KEYS || !uuid(value.id) || value.revision_id !== revisionId || !uuid(value.recipient_workspace_id)
+            || typeof value.allow_use !== 'boolean' || !uuid(value.request_key) || !time(value.created_at)
+            || !(value.revoked_at === null || time(value.revoked_at)))
+            throw unconfirmed('library sharing');
+        return { id: value.id.toLowerCase(), revision_id: revisionId, recipient_workspace_id: value.recipient_workspace_id.toLowerCase(),
+            allow_use: value.allow_use, request_key: value.request_key.toLowerCase(), created_at: value.created_at, revoked_at: value.revoked_at };
+    };
+}
+function dependentRow(kind) {
+    return (value) => {
+        if (!object(value) || keys(value) !== DEPENDENT_KEYS || !uuid(value.id) || value.kind !== kind || !Number.isSafeInteger(value.revision)
+            || value.revision < 1 || typeof value.digest !== 'string' || !SHA256_HEX.test(value.digest) || !time(value.created_at)
+            || typeof value.name !== 'string' || (kind === 'world' ? !uuid(value.world_id) : value.world_id !== null))
+            throw unconfirmed('library dependents');
+        return { id: value.id.toLowerCase(), kind, revision: value.revision, digest: value.digest, created_at: value.created_at,
+            name: value.name, world_id: kind === 'world' ? value.world_id.toLowerCase() : null };
+    };
+}
+/** Other active workspaces of this organization that a version can be shared with (administrators only), by name prefix. */
+export async function listLibraryRecipients(scope, input) {
+    const page = pageNumber(input.page);
+    const params = new URLSearchParams({ page: String(page), page_size: String(PAGE) });
+    if (input.search !== undefined) {
+        // Root counts characters (code points), not UTF-16 units.
+        if ([...input.search].length > 120)
+            throw new CliError('arguments_invalid', 'Use a workspace name prefix of up to 120 characters.', 2);
+        params.set('q', input.search);
+    }
+    const raw = await api(`${base(scope)}/recipients?${params}`, scoped(scope, input.signal));
+    const own = scope.workspace.toLowerCase();
+    return pageOf(raw, page, (value) => {
+        if (!object(value) || keys(value) !== 'id,name' || !uuid(value.id) || value.id.toLowerCase() === own || typeof value.name !== 'string') {
+            throw unconfirmed('library recipients');
+        }
+        return { id: value.id.toLowerCase(), name: value.name };
+    }, 'library recipients');
+}
+/** The sharing grants of one version this workspace owns, newest first, revoked ones included. */
+export async function listLibraryGrants(scope, input) {
+    const revisionId = libraryId(input.revisionId, 'library version id');
+    const page = pageNumber(input.page);
+    const raw = await api(`${base(scope)}/revisions/${revisionId}/grants?page=${page}&page_size=${PAGE}`, scoped(scope, input.signal));
+    return pageOf(raw, page, grantRow(revisionId), 'library sharing');
+}
+/**
+ * Share one exact version with another workspace of this organization, under
+ * the caller's request key. The same key returns the original grant, revoked
+ * or not (never silently renewed); a different recipient or access under it is
+ * refused by root. Administrators only; the human must approve first.
+ */
+export async function shareLibraryVersion(scope, input) {
+    const revisionId = libraryId(input.revisionId, 'library version id');
+    const recipient = libraryId(input.recipientWorkspaceId, 'workspace id');
+    const requestKey = libraryId(input.requestKey, 'request key');
+    if (recipient === scope.workspace.toLowerCase()) {
+        throw new CliError('arguments_invalid', 'Share with another workspace of this organization; this one already owns the version. Nothing was sent.', 2);
+    }
+    const row = grantRow(revisionId)(await api(`${base(scope)}/revisions/${revisionId}/grants`, {
+        ...scoped(scope, input.signal), method: 'POST', body: { request_key: requestKey, recipient_workspace_id: recipient, allow_use: input.allowUse }
+    }));
+    if (row.request_key !== requestKey || row.recipient_workspace_id !== recipient || row.allow_use !== input.allowUse)
+        throw unconfirmed('library sharing');
+    return row;
+}
+/** The caller's original grant under this key, or null when root has none (which does not prove it never arrived). */
+export async function recoverLibraryGrant(scope, input) {
+    const revisionId = libraryId(input.revisionId, 'library version id');
+    const requestKey = libraryId(input.requestKey, 'request key');
+    try {
+        const row = grantRow(revisionId)(await api(`${base(scope)}/revisions/${revisionId}/grants/requests/${requestKey}`, scoped(scope, input.signal)));
+        if (row.request_key !== requestKey)
+            throw unconfirmed('library sharing');
+        return row;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return null;
+        throw error;
+    }
+}
+/** Revoke one grant after the human's approval. Idempotent: an already revoked grant is returned as it is. */
+export async function revokeLibraryGrant(scope, input) {
+    const revisionId = libraryId(input.revisionId, 'library version id');
+    const grantId = libraryId(input.grantId, 'grant id');
+    const row = grantRow(revisionId)(await api(`${base(scope)}/revisions/${revisionId}/grants/${grantId}`, {
+        ...scoped(scope, input.signal), method: 'DELETE', body: { revoke_consent: true }
+    }));
+    if (row.id !== grantId || row.revoked_at === null)
+        throw unconfirmed('library sharing');
+    return row;
+}
+/** This workspace's own world or scenario versions that reference one exact version (25 per page). */
+export async function listLibraryDependents(scope, input) {
+    const revisionId = libraryId(input.revisionId, 'library version id');
+    if (!DEPENDENT_KINDS.includes(input.kind))
+        throw new CliError('arguments_invalid', `Use --kind ${DEPENDENT_KINDS.join('|')} with library dependents.`, 2);
+    const page = pageNumber(input.page);
+    const raw = await api(`${base(scope)}/revisions/${revisionId}/dependents?kind=${input.kind}&page=${page}&page_size=${PAGE}`, scoped(scope, input.signal));
+    return pageOf(raw, page, dependentRow(input.kind), 'library dependents');
+}
+/**
+ * The values a binding would fix, checked against the version's declaration
+ * before anything is sent: only declared names; every required one given;
+ * strings and integers within their declared bounds. Optional parameters left
+ * out take their declared default on the service. Root revalidates all of it,
+ * including the definition's own grammar, which can be stricter.
+ */
+export function checkBindingValues(schema, values) {
+    const fail = (detail) => new CliError('native_library_parameters_invalid', `${detail} Nothing was sent.`, 2);
+    if (!object(values))
+        throw fail('Parameter values must be a JSON object of name to value.');
+    const declared = new Map(schema.parameters.map((item) => [item.name, item]));
+    const unknown = Object.keys(values).filter((name) => !declared.has(name));
+    if (unknown.length)
+        throw fail(`These are not declared parameters of this version: ${unknown.join(', ')}.`);
+    for (const item of schema.parameters) {
+        const value = values[item.name];
+        if (value === undefined) {
+            if (item.required)
+                throw fail(`Parameter ${item.name} is required.`);
+            continue;
+        }
+        // Root counts a string's characters (code points), not its UTF-16 units.
+        if (item.type === 'string' ? typeof value !== 'string' || [...value].length > Math.min(item.maximum, STRING_MAX)
+            : !Number.isSafeInteger(value) || value < (item.minimum ?? 0) || value > item.maximum) {
+            throw fail(item.type === 'string' ? `Parameter ${item.name} must be a string of at most ${item.maximum} characters.`
+                : `Parameter ${item.name} must be a whole number from ${item.minimum} to ${item.maximum}.`);
+        }
+    }
+    return values;
+}
+/**
+ * Bind a parameterized version (owned here, or shared with use) into a new
+ * private immutable resource of this workspace with these exact values, under
+ * the caller's request key. A lost answer is recovered by that key through the
+ * ordinary library request read, never sent under a new key.
+ */
+export async function bindLibraryVersion(scope, input) {
+    const revisionId = libraryId(input.source.id, 'library version id');
+    const requestKey = libraryId(input.requestKey, 'request key');
+    const row = libraryRow(true)(await api(`${base(scope)}/revisions/${revisionId}/bind`, {
+        ...scoped(scope, input.signal), method: 'POST', body: { request_key: requestKey, values: input.values }
+    }));
+    return { ...checkBoundVersion(scope, row, input.source), request_key: requestKey };
+}
+/** True when a library version records a binding of exactly this source version. */
+export const boundFrom = (row, sourceId) => row.parameter_binding?.source_revision_id.toLowerCase() === sourceId.toLowerCase();
+/**
+ * A bound version as root creates it: revision 1 of a new private draft
+ * resource of this workspace, forked from and bound to exactly this source,
+ * with no declaration of its own. The source's kind and digest are checked
+ * when known (an original read back by its key may outlive access to the source).
+ */
+export function checkBoundVersion(scope, row, source) {
+    const sourceId = source.id.toLowerCase();
+    if ((source.kind !== undefined && row.kind !== source.kind) || row.revision !== 1 || row.state !== 'draft' || row.forked_from?.toLowerCase() !== sourceId
+        || row.owner_workspace_id.toLowerCase() !== scope.workspace.toLowerCase() || !row.parameter_binding || !boundFrom(row, sourceId)
+        || (source.digest !== undefined && row.parameter_binding.source_digest !== source.digest) || row.parameter_schema !== null)
+        throw unconfirmed('library binding');
+    return row;
+}