@prestack/thread 0.0.1 → 0.0.3

package/dist/operations/generators/grant.ts

@@ -0,0 +1,336 @@
+import { spawnSync } from 'node:child_process'
+import { createHash, randomBytes } from 'node:crypto'
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, relative } from 'node:path'
+import { argv, stderr, stdin, stdout } from 'node:process'
+import { createInterface } from 'node:readline'
+
+import { exit } from '../../core/invoked.ts'
+import { ELSEWHERE, wordsIn } from '../../core/asking.ts'
+import { generators, settling } from '../../core/chain.ts'
+import { holdsRow, listBounds, showing, withRow } from '../../core/rows.ts'
+import { findTree, inTree } from '../../core/tree.ts'
+
+import { PUBLIC_ROLE as PUBLIC } from '../../core/actor.ts'
+import { ACTOR_FACTS, AGGREGATIONS, COMPARE_OPS, conditioned, said } from '../../core/condition.ts'
+
+import type { Grant } from '../access.ts'
+import { declaredWords, undeclared } from '../access.ts'
+import { descend } from '../../core/descend.ts'
+
+import { operations as woven, types } from './seed.ts'
+
+interface Kept {
+  readonly id: string
+  readonly describes: string
+
+  readonly holds: readonly { readonly id: string; readonly options?: readonly string[] }[]
+  readonly links?: readonly { readonly id: string; readonly to: string }[]
+  readonly actor?: { readonly roles: string; readonly entitlements?: string }
+}
+
+const TREE = findTree()
+
+const FILE = 'access.ts'
+
+const LIST = 'GRANTS'
+
+const RECEIPTS = join(tmpdir(), 'thread-grant')
+
+const RECEIPT = '--receipt'
+
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
+
+const here = (path: string): string => relative(TREE.at, path).split('\\').join('/')
+
+const at = here(inTree(TREE, FILE))
+
+function refuse(because: string): never {
+  stderr.write(`grant: ${because}\n`)
+  exit(1)
+}
+
+const kebab = (one: string): string => one.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+
+import { quoted } from '../../core/rows.ts'
+
+async function taken<T>(file: string, name: string): Promise<readonly T[]> {
+  try {
+    const held = (await import(new URL(`file://${inTree(TREE, file)}`).href)) as Record<string, unknown>
+    const list = held[name]
+    return Array.isArray(list) ? (list as readonly T[]) : []
+  } catch {
+    return []
+  }
+}
+
+const entities = await taken<Kept>('entities.ts', 'ENTITIES')
+
+const declares = (which: 'roles' | 'entitlements'): readonly string[] => declaredWords(entities, which, PUBLIC)
+
+const pass = await descend()
+const operations = [...woven(pass, types(pass))].map(([id]) => ({
+  id,
+  describes: pass.stated.get(id)?.describes ?? '',
+}))
+const grants = await taken<Grant>(FILE, LIST)
+
+if (operations.length === 0) {
+  refuse('this app declares no operations, and a grant permits one. Declare what it can be asked to do first — `thread create operation`.')
+}
+
+const mark = (one: Grant): string =>
+  createHash('sha256').update([one.id, one.on ?? '', one.may.join(','), JSON.stringify(one.to ?? {}), JSON.stringify(one.when ?? {})].join('\n')).digest('hex').slice(0, 6)
+
+const listing = [
+  entities.length === 0
+    ? 'this app keeps nothing, so a grant here names operations and callers and no entity.'
+    : `${String(entities.length)} entity(s) a grant may be written on:`,
+  ...entities.map(
+    (one) =>
+      `  ${one.id} — ${[...one.holds.map((each) => each.id), ...(one.links ?? []).map((each) => each.id)].join(', ')}`,
+  ),
+  '',
+  grants.length === 0
+    ? 'no grants yet, so nothing permits any operation and every caller is refused.'
+    : `${String(grants.length)} grant(s):`,
+
+  ...grants.map(
+    (one) =>
+      `  [${mark(one)}] ${one.id} — may ${one.may.join(', ')}${one.on === undefined ? '' : ` on ${one.on}`} — ${one.describes}`,
+  ),
+].join('\n')
+
+const words = wordsIn(['new'])
+
+stdout.write(`${listing}\n`)
+
+const tree = createHash('sha256').update(TREE.at).digest('hex').slice(0, 16)
+const against = createHash('sha256').update(listing).digest('hex').slice(0, 12)
+const spends = (nonce: string): string => join(RECEIPTS, `${tree}-${nonce}.txt`)
+
+const OPERANDS: readonly { readonly word: string; readonly means: string }[] = [
+  { word: 'field', means: 'a value or link on the row being judged, by its id' },
+  { word: 'value', means: 'a literal — text, a number, true, false, or null' },
+  { word: 'actor', means: `something about who is asking: ${ACTOR_FACTS.join(', ')}` },
+  { word: 'now', means: 'the moment the row is being touched' },
+  { word: 'ago', means: 'a span before now, written like 30d, 12h, 15m, 45s' },
+  { word: 'agg', means: `a count or total over another entity: ${AGGREGATIONS.join(', ')}` },
+]
+
+function method(nonce: string): string {
+  return [
+    'what this makes:',
+    '',
+    `  thread grant new <name> ${RECEIPT} ${nonce}`,
+    '',
+    ...ELSEWHERE,
+    '',
+    `${RECEIPT} is spent by one run and refused if ${at} moved after it was issued.`,
+    '',
+    'what `new` asks:',
+    '',
+    '  name:                             kebab-case, and it names the permission rather than the row',
+    '  what does it permit?              one sentence',
+    ...(entities.length === 0
+      ? []
+      : [`  which entity (blank for none):    ${entities.map((one) => one.id).join(', ')}`]),
+    `  which operations (comma separated): ${operations.map((one) => one.id).join(', ')}`,
+    `  which roles:                      ${declares('roles').join(', ')}`,
+    `                                    ${PUBLIC} is everybody — the role an unauthenticated caller`,
+    '                                    already wears. The rest are the options of the value an',
+    '                                    entity names as saying what a caller may do, so a role',
+    '                                    nothing declares is refused here rather than written',
+    `  which entitlements (blank none):  ${declares('entitlements').join(', ') || 'none are declared'}`,
+    '',
+    'then the condition, one step at a time. Nothing is pasted — each answer is offered from what',
+    'the step before it allows, so a condition that cannot be written cannot be typed:',
+    '',
+    '  is:                               pick a side, below',
+    `  op:                               ${COMPARE_OPS.join(', ')}`,
+    '  than:                             pick the other side',
+    '  and / or / done:                  join another comparison, or stop',
+    '',
+    'what a side may be:',
+    '',
+    ...OPERANDS.map((one) => `  ${one.word.padEnd(8)} ${one.means}`),
+    '',
+    'A grant naming no roles, no entitlements and no condition reading the actor is refused when the',
+    'gate is written — it would admit every caller including one nobody authenticated. So one of',
+    'roles, entitlements, or an `actor` condition is required here.',
+  ].join('\n')
+}
+
+const flagged = argv.indexOf(RECEIPT)
+
+if (flagged === -1) {
+  const nonce = randomBytes(6).toString('hex')
+  mkdirSync(RECEIPTS, { recursive: true })
+  writeFileSync(spends(nonce), `${against}\n`, 'utf8')
+  stdout.write(`\n${method(nonce)}\n`)
+  stdout.write(`\ngrant: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`)
+  stdout.write(`grant:   thread grant new <name> ${RECEIPT} ${nonce}\n`)
+  exit(0)
+}
+
+const offered = argv[flagged + 1]
+if (offered === undefined || offered.startsWith('-')) {
+  refuse(`\`${RECEIPT}\` was handed nothing to check. Run \`thread grant\` with no arguments.`)
+}
+
+let when = ''
+try {
+  when = readFileSync(spends(offered), 'utf8').trim()
+} catch {
+  refuse(`\`${offered}\` is not a receipt this tree issued, or it has been spent — one run per receipt.`)
+}
+rmSync(spends(offered), { force: true })
+if (when !== against) refuse(`${at} has changed since that receipt was issued. Run \`thread grant\` again.`)
+
+const rl = createInterface({ input: stdin, output: stdout })
+const lines = rl[Symbol.asyncIterator]()
+
+const ask = async (question: string): Promise<string> => {
+  stdout.write(question)
+  const next = await lines.next()
+  if (next.done === true) {
+    refuse(
+      `the input ended while this was still asking "${question.trim()}". A grant is not written from ` +
+        'half an answer, so nothing was written. Answer every line the listing names, or run it ' +
+        'without a pipe and answer as you go.',
+    )
+  }
+  return next.value.trim()
+}
+
+const withLinks = (one: Kept): { readonly id: string; readonly fields: readonly string[] } => ({
+  id: one.id,
+  fields: [...one.holds.map((each) => each.id), ...(one.links ?? []).map((each) => each.id)],
+})
+const holdsOnly = (one: Kept): { readonly id: string; readonly fields: readonly string[] } => ({
+  id: one.id,
+  fields: one.holds.map((each) => each.id),
+})
+
+const say = (line: string): void => {
+  stdout.write(line)
+}
+
+const name = kebab(words[1] ?? (await ask('name: ')))
+if (name === '' || !KEBAB.test(name)) {
+  rl.close()
+  refuse(`"${name}" cannot be the id of a grant — it is kebab-case, e.g. owner-reads-own-invoice`)
+}
+if (grants.some((one) => one.id === name)) {
+  rl.close()
+  refuse(`\`${name}\` is already granted in ${at}. One id, one policy — two would silently keep whichever was written second.`)
+}
+
+const describes = await ask('what does it permit? ')
+if (describes === '') {
+  rl.close()
+  refuse(`\`${name}\` was given no meaning, and a row without one is a name nobody can read`)
+}
+
+const on = entities.length === 0 ? '' : await ask(`which entity (blank if it acts on none) — ${entities.map((one) => one.id).join(', ')}: `)
+const entity = on === '' ? undefined : entities.find((one) => one.id === on)
+if (on !== '' && entity === undefined) {
+  rl.close()
+  refuse(`nothing declares \`${on}\`, and a grant on an entity that does not exist enforces nothing`)
+}
+
+const may = (await ask(`which operations (comma separated) — ${operations.map((one) => one.id).join(', ')}: `))
+  .split(',')
+  .map((one) => one.trim())
+  .filter((one) => one !== '')
+const stray = may.filter((one) => !operations.some((each) => each.id === one))
+if (may.length === 0 || stray.length > 0) {
+  rl.close()
+  refuse(
+    stray.length > 0
+      ? `this app declares no operation called ${stray.join(', ')} — it declares ${operations.map((one) => one.id).join(', ')}`
+      : 'a grant permits at least one operation, or it permits nothing and may as well not be written',
+  )
+}
+
+const named = (which: 'roles' | 'entitlements', answered: string): readonly string[] => {
+  const wrong = undeclared(answered, declares(which), which)
+  if (wrong !== undefined) refuse(wrong)
+  return answered.split(',').map((one) => one.trim()).filter((one) => one !== '')
+}
+
+const listed = declares('roles')
+const granted = declares('entitlements')
+
+const roles = named('roles', await ask(`which roles (comma separated) — ${listed.join(', ')}: `))
+const entitlements = named(
+  'entitlements',
+  await ask(`which entitlements (blank for none)${granted.length === 0 ? '' : ` — ${granted.join(', ')}`}: `),
+)
+
+const condition =
+  entity === undefined
+    ? undefined
+    : await conditioned((_key, question) => ask(question), say, withLinks(entity), entities.map(holdsOnly))
+rl.close()
+
+const to =
+  roles.length === 0 && entitlements.length === 0
+    ? undefined
+    : { ...(roles.length === 0 ? {} : { roles }), ...(entitlements.length === 0 ? {} : { entitlements }) }
+
+const row = [
+  '  {',
+  `    id: ${quoted(name)},`,
+  `    at: ${quoted(at)},`,
+  `    describes: ${quoted(describes)},`,
+  '    version: 1,',
+  `    may: [${may.map((one) => quoted(one)).join(', ')}],`,
+  ...(on === '' ? [] : [`    on: ${quoted(on)},`]),
+  ...(to === undefined ? [] : [`    to: ${said(to)},`]),
+  ...(condition === undefined ? [] : [`    when: ${said(condition)},`]),
+  '  },',
+].join('\n')
+
+const path = inTree(TREE, FILE)
+const text = readFileSync(path, 'utf8')
+const where = listBounds(text, LIST)
+if (where === undefined) refuse(`${at} states no \`${LIST}\` list to grant in`)
+if (holdsRow(text, where, name)) refuse(`\`${name}\` is already granted in ${at}`)
+
+writeFileSync(path, withRow(text, where, row), 'utf8')
+stdout.write(`grant: ${name} may ${may.join(', ')}${on === '' ? '' : ` on ${on}`}, written into ${at}.\n`)
+
+const settled = settling(TREE.at, await generators(TREE), ['thread grant'])
+for (const one of settled.ran) stdout.write(`${one}\n`)
+
+const refused = settled.unsettled.filter((one) => one.includes('permits'))
+
+if (refused.length > 0) {
+  writeFileSync(path, text, 'utf8')
+  stderr.write(
+    `grant: \`${name}\` was taken back out of ${at}, because ${refused.join(', ')} would not settle ` +
+      `after ${String(settled.rounds)} round(s) — the refusal above says what it wanted instead. Nothing else moved.\n`,
+  )
+  exit(1)
+}
+
+if (settled.unsettled.length > 0) {
+  stderr.write(
+    `grant: \`${name}\` is written and stands — the gate generator accepted it. What did not settle is ` +
+      `${settled.unsettled.join(', ')}, which is about the rest of this tree rather than about this row. ` +
+      'Run it yourself and read what it says.\n',
+  )
+}
+
+const records = spawnSync('npx', ['thread'], { cwd: TREE.at, encoding: 'utf8' })
+if (`${records.stdout ?? ''}`.includes('written')) {
+  const kept = spawnSync('npx', ['thread', 'written'], { cwd: TREE.at, encoding: 'utf8' })
+  if (kept.status !== 0) {
+    stdout.write(`${`${kept.stdout ?? ''}${kept.stderr ?? ''}`.trim()}\n`)
+    stderr.write("grant: the row is written and stands; recording it as the method's was refused above.\n")
+  }
+}
+
+exit(0)