@frontera-sdk/cli 1.50.79 → 1.50.81

package/src/commands/marking/index-commands.ts

@@ -0,0 +1,171 @@
+import { BlueprintAuthoringApi, type MarkingPrincipal } from '../../api/blueprint-authoring-api'
+import { UsageError } from '../../errors'
+import { table } from '../../table'
+import { flagString, type Command, type CommandContext } from '../types'
+
+/**
+ * Security markings — the audiences a marked Blueprint row is visible to.
+ *
+ * Its own noun rather than verbs under `blueprint`, because `blueprint create`,
+ * `grant` and `delete` already mean object types there. Declarative Blueprint
+ * files say WHICH column carries a row's markings (`markingsColumn`); nothing
+ * there registers a marking or grants one, so this does not duplicate them.
+ *
+ * Every verb needs a person's session. The service gates reads on `role:read`
+ * and writes on `role:create` / `role:update`, at organization scope. `role` is
+ * non-delegable, so no organization key can ever hold it; the router is also
+ * closed to organization-key writes, because granting a marking grants an
+ * audience; and a workspace key never satisfies an organization-scoped check.
+ * So all five verbs declare the session lane — the dispatcher refuses a key
+ * before any request — and name where a person does this in the platform.
+ * They also declare organization scope themselves: the registry has no
+ * workspace, so `--workspace` is refused rather than silently ignored.
+ */
+
+const KINDS = ['workspace', 'role', 'user', 'agent'] as const
+
+function api(ctx: CommandContext): BlueprintAuthoringApi {
+  return new BlueprintAuthoringApi(ctx.apiUrl, ctx.token)
+}
+
+/** `role:analyst` → `{ kind: 'role', id: 'analyst' }`. Split on the first colon only. */
+export function parsePrincipal(raw: string | undefined, example: string): MarkingPrincipal {
+  const at = raw?.indexOf(':') ?? -1
+  const kind = at > 0 ? raw!.slice(0, at) : ''
+  const id = at > 0 ? raw!.slice(at + 1) : ''
+  if (!(KINDS as readonly string[]).includes(kind) || !id) {
+    throw new UsageError(
+      raw ? `"${raw}" is not a principal` : 'missing <principal>',
+      `write it as <kind>:<id>, kind one of ${KINDS.join(', ')} — e.g. ${example}`,
+    )
+  }
+  return { kind: kind as MarkingPrincipal['kind'], id }
+}
+
+const list: Command = {
+  meta: {
+    noun: 'marking',
+    verb: 'list',
+    authLane: 'session',
+    scope: 'organization',
+    sessionAlternative: 'Blueprint → Access → Markings',
+    args: [],
+    flags: {},
+    summary: 'List the security markings registered in this organization',
+    examples: ['frontera marking list', 'frontera marking list --json'],
+  },
+  async run(ctx) {
+    const { markings } = await api(ctx).markings()
+    return {
+      data: markings,
+      text:
+        markings.length === 0
+          ? 'No security markings in this organization.'
+          : table(
+              ['marking', 'display name', 'description'],
+              markings.map((m) => [m.marking, m.displayName ?? '', m.description ?? '']),
+              [undefined, 40, 60],
+            ),
+    }
+  },
+}
+
+const create: Command = {
+  meta: {
+    noun: 'marking',
+    verb: 'create',
+    authLane: 'session',
+    scope: 'organization',
+    sessionAlternative: 'Blueprint → Access → Markings',
+    args: [{ name: 'marking', required: true, description: '1-64 letters, digits and _ : . -' }],
+    flags: { 'display-name': 'string', description: 'string' },
+    summary: 'Register a security marking, or restore a retired one',
+    examples: [
+      'frontera marking create pii --display-name "Personal data"',
+      'frontera marking create finance:restricted --description "Board finance only"',
+    ],
+  },
+  async run(ctx) {
+    const marking = ctx.positional[0]
+    if (!marking) throw new UsageError('missing <marking>', 'frontera marking create pii')
+    const displayName = flagString(ctx, 'display-name')
+    const description = flagString(ctx, 'description')
+
+    const result = await api(ctx).createMarking({
+      marking,
+      ...(displayName === undefined ? {} : { displayName }),
+      ...(description === undefined ? {} : { description }),
+    })
+    return {
+      data: result,
+      text: `Registered marking "${result.marking}".\n`
+        + `  grant it: frontera marking grant ${result.marking} role:<role>`,
+    }
+  },
+}
+
+const grants: Command = {
+  meta: {
+    noun: 'marking',
+    verb: 'grants',
+    authLane: 'session',
+    scope: 'organization',
+    sessionAlternative: 'Blueprint → Access → Markings',
+    args: [{ name: 'principal', required: true, description: '<kind>:<id> — workspace, role, user or agent' }],
+    flags: {},
+    summary: 'List the markings granted directly to one principal',
+    examples: [
+      'frontera marking grants role:analyst',
+      'frontera marking grants workspace:<workspace-id> --json',
+    ],
+  },
+  async run(ctx) {
+    const principal = parsePrincipal(ctx.positional[0], 'role:analyst')
+    const { markings } = await api(ctx).principalMarkings(principal)
+    const who = `${principal.kind} "${principal.id}"`
+    return {
+      data: { principalKind: principal.kind, principalId: principal.id, markings },
+      text: markings.length === 0
+        ? `No markings granted to ${who}.`
+        : `${who}: ${markings.join(', ')}`,
+    }
+  },
+}
+
+function grantCommand(verb: 'grant' | 'revoke'): Command {
+  const revoke = verb === 'revoke'
+  return {
+    meta: {
+      noun: 'marking',
+      verb,
+      authLane: 'session',
+      scope: 'organization',
+      sessionAlternative: 'Blueprint → Access → Markings',
+      args: [
+        { name: 'marking', required: true, description: 'A registered marking, from `frontera marking list`' },
+        { name: 'principal', required: true, description: '<kind>:<id> — workspace, role, user or agent' },
+      ],
+      flags: {},
+      summary: revoke
+        ? 'Revoke a marking from a principal, effective on its next request'
+        : 'Grant a marking to a workspace, role, user or agent',
+      examples: revoke
+        ? ['frontera marking revoke pii role:analyst']
+        : ['frontera marking grant pii role:analyst', 'frontera marking grant pii workspace:<workspace-id>'],
+    },
+    async run(ctx) {
+      const [marking, raw] = ctx.positional
+      if (!marking) throw new UsageError('missing <marking>', `frontera marking ${verb} pii role:analyst`)
+      const principal = parsePrincipal(raw, `frontera marking ${verb} ${marking} role:analyst`)
+
+      if (revoke) await api(ctx).revokeMarking(marking, principal)
+      else await api(ctx).grantMarking(marking, principal)
+      return {
+        data: { marking, principalKind: principal.kind, principalId: principal.id, [revoke ? 'revoked' : 'granted']: true },
+        text: `${revoke ? 'Revoked' : 'Granted'} "${marking}" ${revoke ? 'from' : 'to'} ${principal.kind} "${principal.id}".`,
+      }
+    },
+  }
+}
+
+export const markingCommands: Command[] = [list, create, grants, grantCommand('grant'), grantCommand('revoke')]