heyquilt 0.3.122 → 0.3.138

package/src/seam-access.js

@@ -0,0 +1,97 @@
+// Who each AI in a session that is a quilt is to Seam, with nothing set up by hand (Seam's
+// plans/quilt-source-control/11.5). Seam takes Quilt's sign-ins through Quilt's identity service
+// (GET /v1/seam/me on the accounts API): a person's Quilt sign-in is that person
+// (person:<user id>), and a person's AI sessions on their computer are the person; an agent's
+// Quilt key or pass (a cloud AI, a hosted agent) is that agent (agent:<id>), working for its
+// person. SEAM_TOKEN, when set, is used as it is.
+//
+// An agent's own key only reads on Seam: it writes with an agent token. This trades the key for
+// one per quilt, for the squares it works in (merge when its person holds merge, else write),
+// and keeps it until a quarter of an hour before it ends: never once per call, which would
+// reach Seam's 20 live tokens per agent. A token for other squares is revoked when a new one is made.
+import { quiltClient } from '@heyquilt/seam/lib/quilts/client.js'
+
+export const RENEW_MS = 15 * 60_000
+
+/** Whether a credential is an agent's own (a Quilt agent key or pass, or a Seam agent's key from `seam agent new`), which trades for an agent token. */
+export const isAgentKey = (token) => /^(?:QuiltPass |qa_|sak_)/.test(String(token || ''))
+
+/**
+ * Seam clients for one member, on Seam at `api` (a URL, or a function giving it at call time).
+ * `credential()` resolves to the token they sign in to Seam with
+ * (or null). `client(quilt, squares)` is a client acting as them in `quilt`; for an agent, with
+ * a token that reaches `squares` (ids; none: the squares it holds); one that only reads (`read`)
+ * takes the token it holds there already, whatever its squares. Its `token` is the one it uses.
+ */
+export function seamAccess ({ api, credential, make = quiltClient, now = Date.now, fetch: fetchImpl = globalThis.fetch }) {
+  const minted = new Map() // quilt -> { token, id, expires_at, max_level, squares }
+  const where = () => typeof api === 'function' ? api() : api
+  // A trade refused 404: Seam finds no quilt this agent reaches through the person it works for (an
+  // agent needs no member row of its own: Seam takes the person's). So the person is not in the quilt,
+  // or the quilt is gone: the agent is told who that person is to Seam, to pass on.
+  async function noQuilt (quilt, key) {
+    let person = ''
+    try {
+      const res = await fetchImpl(`${String(where()).replace(/\/+$/, '')}/v1/me`, { headers: { authorization: /^QuiltPass /.test(key) ? key : `Bearer ${key}` }, signal: AbortSignal.timeout(10_000) })
+      const me = res.ok ? await res.json() : null
+      if (me && typeof me.on_behalf_of === 'string') person = me.on_behalf_of
+    } catch {}
+    const who = person || 'the person you work for'
+    return `Seam finds no quilt ${quilt} that the person this agent works for (${who}) is in: they are not a member of it, or it was deleted. Tell them: a quilt admin adds them once (seam quilts add ${person || 'person:<their id>'} --level write --quilt ${quilt}), and this agent then works there for them.`
+  }
+  async function mint (quilt, key, squares) {
+    const own = make({ api: where(), token: key })
+    const was = minted.get(quilt)
+    const body = { squares: squares && squares.length ? squares : 'own' }
+    let t
+    try { t = await own.createAgentToken(quilt, { ...body, max_level: 'merge' }) } catch (err) {
+      if (err.status === 404) throw Object.assign(new Error(await noQuilt(quilt, key)), { status: 404, code: 'no_quilt' })
+      // Its person holds write, not merge: a token that writes, and merges wait for a person.
+      if (err.status !== 403) throw err
+      t = await own.createAgentToken(quilt, { ...body, max_level: 'write' })
+    }
+    const kept = { token: t.token, id: t.id, expires_at: Number(t.expires_at) || now() + 8 * 3600e3, max_level: t.max_level || 'write', squares: body.squares }
+    minted.set(quilt, kept)
+    if (was && was.id && was.id !== kept.id && own.revokeAgentToken) own.revokeAgentToken(quilt, was.id).catch(() => {})
+    return kept
+  }
+  return {
+    async client (quilt, squares = [], { read = false, retry } = {}) {
+      const at = where()
+      if (!at) throw new Error('Seam is not on for this app (QUILT_SOURCE_URL is not set).')
+      const key = await credential()
+      if (!key) throw new Error('This session has no Quilt sign-in to reach Seam with: sign in to Quilt (quilt login) and join again.')
+      // `retry: false`: a read that has somewhere else to go (quilt_history: the relay) is not held up by a Seam that is down.
+      const made = (token) => make({ api: at, token, ...(retry === false ? { retry: false } : {}) })
+      if (!isAgentKey(key) || !quilt) return { client: made(key), token: key, person: !isAgentKey(key) }
+      // An agent's own key does not even read a quilt it is not a member of (it reaches it through
+      // its person only with a token), so reading uses whichever token it holds there now.
+      const want = squares && squares.length ? squares : 'own'
+      let t = minted.get(quilt)
+      const fresh = t && t.expires_at - now() >= RENEW_MS
+      if (!fresh || (!read && JSON.stringify(t.squares) !== JSON.stringify(want))) t = await mint(quilt, key, squares)
+      return { client: made(t.token), token: t.token, level: t.max_level, person: false }
+    },
+    /** Forgets the tokens it made (a refused one is made again on the next call). */
+    forget () { minted.clear() }
+  }
+}
+
+/** The credential a folder's session reaches Seam with: SEAM_TOKEN, else its Quilt sign-in (`apiAuth`: the person's, or its agent's key). */
+export function sessionCredential ({ env = process.env, apiAuth = null, account = () => null } = {}) {
+  return async () => {
+    if (env.SEAM_TOKEN) return env.SEAM_TOKEN
+    if (apiAuth) { try { const a = await apiAuth(); if (a && a.token) return a.token } catch {} }
+    const acc = account()
+    return (acc && acc.token) || null
+  }
+}
+
+/** Who `token` is to Seam at `api` (GET /v1/me): { member_id, kind, on_behalf_of? }, or null when Seam can't say. */
+export async function seamWhoAmI (api, token, { fetch: fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const res = await fetchImpl(`${String(api).replace(/\/+$/, '')}/v1/me`, { headers: { authorization: /^QuiltPass /.test(token) ? token : `Bearer ${token}` }, signal: AbortSignal.timeout(10_000) })
+    const me = res.ok ? await res.json() : null
+    return me && typeof me.member_id === 'string' ? me : null
+  } catch { return null }
+}

package/src/seam-claims.js

@@ -0,0 +1,53 @@
+// Letting go of claims in a session that is a quilt (layout 3): its claims are Seam's, and each
+// member lets go of theirs in Seam as themselves (Session.releaseInSeam). The move into Seam made
+// the session's claims as the member who moved it (Seam makes a claim only as its caller), so the
+// relay keeps whose each was (`moved`, server.js quilt-claims): those are their claimant's to let
+// go of, not the mover's, and the session owner may let go of any one named.
+import { seamWhoAmI } from './seam-access.js'
+
+/**
+ * Which of Seam's `claims` this member lets go of for `pattern` ('*': all of theirs): { release,
+ * notYours: [{ pattern, holder }] }. `me`: the member's Seam id; `moved`: the relay's records of the
+ * move's claims ({ id, by, mine }); `owner`: the session owner, who lets go of any claim it names.
+ */
+export function claimsToRelease ({ claims = [], me = '', moved = [], pattern = '*', owner = false }) {
+  const all = !pattern || pattern === '*'
+  const rec = new Map((moved || []).map((m) => [m.id, m]))
+  const release = []
+  const notYours = []
+  for (const c of claims || []) {
+    if (!c || c.conflict || (!all && c.pattern !== pattern)) continue
+    const m = rec.get(c.id)
+    const theirs = m ? !!m.mine : !!me && c.holder === me
+    if (theirs || (owner && !all)) release.push(c)
+    else if (!all) notYours.push({ pattern: c.pattern, holder: m ? `${m.by || 'someone'} (moved into Seam with the session)` : (c.holder_name || c.holder) })
+  }
+  return { release, notYours }
+}
+
+/**
+ * Lets go of this member's claims for `pattern` in Seam: `access` is the member's seamAccess (a
+ * person's sign-in, or an agent's key traded for a token that reaches the claims' squares); `asked`
+ * the relay's quilt-claims answer ({ moved, owner }). Resolves to { released, seam: true, held?,
+ * gone: [claim ids let go of] }; throws naming the holder when the one named is someone else's.
+ */
+export async function releaseInSeam ({ access, api, quilt, asked = {}, pattern = '*' }) {
+  const { client: reader, token } = await access.client(quilt, [], { read: true })
+  const me = await seamWhoAmI(api, token)
+  const got = await reader.claims(quilt)
+  const claims = Array.isArray(got) ? got : (got && got.claims) || []
+  const pick = claimsToRelease({ claims, me: (me && me.member_id) || '', moved: asked.moved, owner: !!asked.owner, pattern })
+  if (!pick.release.length && pick.notYours.length) throw new Error(`${pattern} is claimed by ${pick.notYours[0].holder}; only they can release it (or the session owner)`)
+  if (!pick.release.length) return { released: 0, seam: true, gone: [] }
+  const { client } = await access.client(quilt, [...new Set(pick.release.map((c) => c.square_id))])
+  const gone = []
+  const held = []
+  for (const c of pick.release) {
+    try { await client.unclaim(quilt, c.square_id, c.id); gone.push(c.id) } catch (err) {
+      if (err.code === 'claim_queued') { held.push(c.pattern); continue }
+      if (err.status === 404) { gone.push(c.id); continue } // let go of already
+      throw err
+    }
+  }
+  return { released: gone.length, seam: true, gone, ...(held.length ? { held } : {}) }
+}

package/src/seam-url.js

@@ -0,0 +1,15 @@
+// Where the app and the CLI find Seam, Quilt's source control (Seam's plans/quilt-source-control/16).
+// On by default: QUILT_SOURCE_URL names another Seam, and `off` (or an empty value) turns it off.
+// Only the app's side reads this. The relay and the API read QUILT_SOURCE_URL themselves and stay
+// off without it. It changes nothing for a session the relay does not say is linked to a quilt.
+
+export const SEAM_URL = 'https://api.seam.heyquilt.com'
+
+/** The app's Seam API, or '' when it is turned off. */
+export function appSeamUrl (env = process.env) {
+  const v = env ? env.QUILT_SOURCE_URL : undefined
+  if (v === undefined || v === null) return SEAM_URL
+  const t = String(v).trim()
+  if (!t || /^(off|0|false|no|none)$/i.test(t)) return ''
+  return t.replace(/\/+$/, '')
+}