@pathmx/core 0.5.0

package/authority/actors.ts

@@ -0,0 +1,271 @@
+import type { Plugin } from "../plugins/types.ts"
+import { SourceDiagnosticError } from "../source-diagnostic.ts"
+import type { Source } from "../source/index.ts"
+import type {
+  Actor,
+  ActorProfile,
+  ActorProfileRef,
+  ActorProfiles,
+  AgentActor,
+  KnownActorIndex,
+  UserActor,
+} from "./model.ts"
+
+const USERNAME = /^[a-z0-9][a-z0-9._-]*$/
+
+export function isActorSource(source: Source) {
+  return (
+    source.type === "user" ||
+    (source.type === "agent" && source.data.actor === true)
+  )
+}
+
+export class ActorSourceError extends SourceDiagnosticError {
+  readonly sourceId: string
+
+  constructor(source: Source, message: string) {
+    super({
+      source: source.path,
+      plugin: "actors",
+      message: `Invalid Actor Source ${source.id}: ${message}`,
+    })
+    this.name = "ActorSourceError"
+    this.sourceId = source.id
+  }
+}
+
+export function normalizeEmail(value: string) {
+  return value.trim().toLowerCase()
+}
+
+function requiredString(source: Source, field: string) {
+  const value = source.data[field]
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ActorSourceError(source, `${field} is required`)
+  }
+  return value.trim()
+}
+
+function optionalString(source: Source, field: string) {
+  const value = source.data[field]
+  if (value == null || value === "") return
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ActorSourceError(source, `${field} must be a non-empty string`)
+  }
+  return value.trim()
+}
+
+function stringList(source: Source, field: string) {
+  const value = source.data[field]
+  if (!Array.isArray(value) || !value.length) {
+    throw new ActorSourceError(source, `${field} must be a non-empty list`)
+  }
+  const strings = value.map((item) =>
+    typeof item === "string" ? item.trim() : "",
+  )
+  if (strings.some((item) => !item)) {
+    throw new ActorSourceError(source, `${field} must contain only strings`)
+  }
+  return strings
+}
+
+function profileFor(source: Source): ActorProfile {
+  const username = optionalString(source, "username") ?? source.name
+  if (!USERNAME.test(username)) {
+    throw new ActorSourceError(source, `invalid username: ${username}`)
+  }
+  const avatar = optionalString(source, "avatar")
+  return Object.freeze({
+    name: requiredString(source, "name"),
+    username,
+    ...(avatar ? { avatar } : {}),
+  })
+}
+
+function homeFor(source: Source) {
+  const suffix = `.${source.type}`
+  if (!source.id.endsWith(suffix)) {
+    throw new ActorSourceError(
+      source,
+      `id must end in ${suffix} so its Home can be derived`,
+    )
+  }
+  return source.id.slice(0, -suffix.length)
+}
+
+function actorFor(source: Source): {
+  actor: Actor
+  emails: readonly string[]
+} {
+  const profile = profileFor(source)
+  const base = {
+    id: source.id,
+    profile,
+    home: homeFor(source),
+  }
+  if (source.type === "agent") {
+    const actor: AgentActor = Object.freeze({ ...base, type: "agent" })
+    return { actor, emails: [] }
+  }
+  if (source.type !== "user") {
+    throw new ActorSourceError(source, `unsupported Actor type: ${source.type}`)
+  }
+  const authoredRole = source.data.role
+  const role =
+    authoredRole == null || authoredRole === "" ? "member" : authoredRole
+  if (role !== "member" && role !== "staff") {
+    throw new ActorSourceError(source, `role must be member or staff`)
+  }
+  const emails = stringList(source, "emails").map(normalizeEmail)
+  if (new Set(emails).size !== emails.length) {
+    throw new ActorSourceError(source, `emails must be unique`)
+  }
+  const actor: UserActor = Object.freeze({ ...base, type: "user", role })
+  return { actor, emails }
+}
+
+export class ActorDirectory implements KnownActorIndex {
+  private actors = new Map<string, Actor>()
+  private usernames = new Map<string, Actor>()
+  private emails = new Map<string, UserActor>()
+  private homes = new Map<string, Actor>()
+  private sourceActors = new Map<string, string>()
+  private actorEmails = new Map<string, readonly string[]>()
+
+  readonly profiles: ActorProfiles = Object.freeze({
+    findById: (id: string) => this.profileRef(this.actors.get(id)),
+    findByUsername: (username: string) =>
+      this.profileRef(this.usernames.get(username)),
+  })
+
+  findActorById(id: string) {
+    return this.actors.get(id)
+  }
+
+  findHomeOwner(path: string) {
+    let candidate = path.replace(/\/+$/, "") || "/"
+    while (candidate) {
+      const actor = this.homes.get(candidate)
+      if (actor) return actor
+      const slash = candidate.lastIndexOf("/")
+      if (slash <= 0) return this.homes.get("/")
+      candidate = candidate.slice(0, slash)
+    }
+  }
+
+  findById(id: string) {
+    return this.profileRef(this.actors.get(id))
+  }
+
+  findByUsername(username: string) {
+    return this.profileRef(this.usernames.get(username))
+  }
+
+  findUserByEmail(email: string) {
+    return this.emails.get(normalizeEmail(email))
+  }
+
+  credentialUsers() {
+    return this.all()
+      .filter((actor): actor is UserActor => actor.type === "user")
+      .map((actor) => ({
+        actor,
+        emails: this.actorEmails.get(actor.id) ?? [],
+      }))
+  }
+
+  all() {
+    return [...this.actors.values()].sort((a, b) => a.id.localeCompare(b.id))
+  }
+
+  index(source: Source) {
+    if (!isActorSource(source)) return
+    const { actor, emails } = actorFor(source)
+    const idOwner = this.actors.get(actor.id)
+    if (idOwner) {
+      throw new ActorSourceError(source, `duplicate Actor id: ${actor.id}`)
+    }
+    const usernameOwner = this.usernames.get(actor.profile.username)
+    if (usernameOwner) {
+      throw new ActorSourceError(
+        source,
+        `duplicate username: ${actor.profile.username}`,
+      )
+    }
+    if (this.homes.has(actor.home)) {
+      throw new ActorSourceError(source, `duplicate Home: ${actor.home}`)
+    }
+    for (const email of emails) {
+      if (this.emails.has(email)) {
+        throw new ActorSourceError(
+          source,
+          `duplicate normalized email: ${email}`,
+        )
+      }
+    }
+
+    this.actors.set(actor.id, actor)
+    this.usernames.set(actor.profile.username, actor)
+    this.homes.set(actor.home, actor)
+    this.sourceActors.set(source.path, actor.id)
+    this.actorEmails.set(actor.id, emails)
+    if (actor.type === "user") {
+      for (const email of emails) this.emails.set(email, actor)
+    }
+  }
+
+  unindex(sourcePath: string) {
+    const actorId = this.sourceActors.get(sourcePath)
+    if (!actorId) return
+    const actor = this.actors.get(actorId)
+    this.sourceActors.delete(sourcePath)
+    this.actors.delete(actorId)
+    if (actor) this.usernames.delete(actor.profile.username)
+    if (actor) this.homes.delete(actor.home)
+    for (const email of this.actorEmails.get(actorId) ?? []) {
+      this.emails.delete(email)
+    }
+    this.actorEmails.delete(actorId)
+  }
+
+  private profileRef(actor?: Actor): ActorProfileRef | undefined {
+    return actor ? { id: actor.id, profile: actor.profile } : undefined
+  }
+}
+
+export function ActorDirectoryPlugin(directory: ActorDirectory): Plugin {
+  return {
+    id: "actors",
+    name: "ActorDirectoryPlugin",
+    schema: {
+      sources: {
+        user: {
+          label: "User",
+          icon: "circle-user",
+          color: "blue",
+        },
+        agent: {
+          label: "Agent",
+          icon: "bot",
+          color: "purple",
+        },
+      },
+    },
+    index(source) {
+      directory.index(source)
+    },
+    unindex(sourcePath) {
+      directory.unindex(sourcePath)
+    },
+    invalidate(transition) {
+      const actors = new Set<string>()
+      if (transition.before && isActorSource(transition.before)) {
+        actors.add(transition.before.id)
+      }
+      if (transition.after && isActorSource(transition.after)) {
+        actors.add(transition.after.id)
+      }
+      return actors.size ? { targets: [{ type: "actor", actors }] } : undefined
+    },
+  }
+}

package/authority/agents.ts

@@ -0,0 +1,95 @@
+import { AccessDeniedError } from "./access.ts"
+import { createTransaction } from "../actions/transaction.ts"
+import type { BlockDraft, BlockUpdate } from "../source/index.ts"
+import type { Engine } from "../host/engine.ts"
+import type { AgentActor, Principal } from "./model.ts"
+import type { KnownActorIndex } from "./model.ts"
+
+export class AgentAdmissionError extends Error {
+  constructor(message = "Agent job admission denied.") {
+    super(message)
+    this.name = "AgentAdmissionError"
+  }
+}
+
+export type AgentJobContext = Readonly<{
+  actor: AgentActor
+  principal: Principal
+  sourceId: string
+  appendBlock(block: BlockDraft): void
+  updateBlock(id: string, update: BlockUpdate): void
+}>
+
+export type AgentJob = (context: AgentJobContext) => void | Promise<void>
+
+export type AgentAdmission = Readonly<{
+  agentId: string
+  targetId: string
+  operationId: string
+}>
+
+export async function runAgentJob(
+  engine: Engine,
+  admission: AgentAdmission,
+  job: AgentJob,
+) {
+  return engine.runAgentJob(admission, job)
+}
+
+export async function runAgentJobWithIndex(
+  engine: Engine,
+  actors: KnownActorIndex,
+  admission: AgentAdmission,
+  job: AgentJob,
+) {
+  const { agentId, targetId, operationId } = admission
+  if (!operationId.trim()) throw new AgentAdmissionError()
+  const agent = actors.findActorById(agentId)
+  if (!agent || agent.type !== "agent") throw new AgentAdmissionError()
+
+  return engine.commitPrepared(async () => {
+    const target = engine.repo.get(targetId)
+    if (!target) throw new AgentAdmissionError()
+    const principal: Principal = { type: "actor", actor: agent }
+    if (engine.readAccess(principal, target) === "denied") {
+      throw new AgentAdmissionError()
+    }
+    if (
+      target.blocks.some((block) => block.data.operation_id === operationId)
+    ) {
+      return { changes: [] }
+    }
+
+    const tx = createTransaction(engine, agent)
+    const source = tx.source(target.id)
+    await job({
+      actor: agent,
+      principal,
+      sourceId: target.id,
+      appendBlock(block) {
+        source.appendBlock({
+          ...block,
+          data: { ...block.data, operation_id: operationId },
+        })
+      },
+      updateBlock(id, update) {
+        source.updateBlock(id, (current) => {
+          const patch = typeof update === "function" ? update(current) : update
+          return {
+            ...patch,
+            data: { ...patch.data, operation_id: operationId },
+          }
+        })
+      },
+    })
+    const changes = await tx.changeSet()
+    if (
+      changes.changes.some(
+        (change) => engine.repo.pathToId(change.path) !== target.id,
+      )
+    ) {
+      throw new AccessDeniedError("agent-target-only")
+    }
+    return changes
+  })
+}

package/authority/credentials.ts

@@ -0,0 +1,144 @@
+import type { CredentialSession, KnownActorIndex, UserActor } from "./model.ts"
+
+export type CredentialLink<Method extends "get" | "post" = "get" | "post"> =
+  Readonly<{
+    method: Method
+    href: string
+  }>
+
+export type ExternalIdentity = Readonly<{
+  provider: string
+  subject: string
+  email?: string
+  claims?: Readonly<Record<string, unknown>>
+}>
+
+export type ExternalIdentityHint = Readonly<{
+  provider: string
+  email?: string
+}>
+
+export type CredentialCandidate = Readonly<{
+  identity: ExternalIdentityHint
+  profile: Readonly<{ name: string; avatar?: string }>
+}>
+
+export type CredentialDirectory = Readonly<{
+  candidates(): readonly CredentialCandidate[]
+  allows(identity: ExternalIdentityHint): Promise<boolean>
+  admit(identity: ExternalIdentity): Promise<UserActor | undefined>
+}>
+
+export type ActorAdmission = Readonly<{
+  bind(actors: KnownActorIndex): CredentialDirectory
+}>
+
+export type CredentialProvider = Readonly<{
+  signIn: CredentialLink<"get"> | null
+  ready(directory: CredentialDirectory): Promise<void>
+  resolve(request: Request): Promise<
+    | Readonly<{
+        identity: ExternalIdentity
+        signOut: CredentialLink<"post"> | null
+      }>
+    | undefined
+  >
+  fetch(request: Request, directory: CredentialDirectory): Promise<Response>
+  close(): Promise<void>
+}>
+
+export type CredentialHost = Readonly<{
+  ready(actors: KnownActorIndex): Promise<void>
+  resolve(request: Request, actors: KnownActorIndex): Promise<CredentialSession>
+  fetch(request: Request, actors: KnownActorIndex): Promise<Response>
+  close(): Promise<void>
+}>
+
+/** Map verified provider identities to pre-authored User Actors by email. */
+export function rosteredActorAdmission(): ActorAdmission {
+  return {
+    bind(actors) {
+      return Object.freeze({
+        candidates: () =>
+          actors.credentialUsers().flatMap(({ actor, emails }) =>
+            emails.map((email) => ({
+              identity: { provider: "email", email },
+              profile: {
+                name: actor.profile.name,
+                ...(actor.profile.avatar
+                  ? { avatar: actor.profile.avatar }
+                  : {}),
+              },
+            })),
+          ),
+        async allows(identity) {
+          return Boolean(
+            identity.email && actors.findUserByEmail(identity.email),
+          )
+        },
+        async admit(identity) {
+          return identity.email
+            ? actors.findUserByEmail(identity.email)
+            : undefined
+        },
+      })
+    },
+  }
+}
+
+/** Compose authentication protocol mechanics with application Actor policy. */
+export function createCredentialHost(
+  provider: CredentialProvider,
+  admission: ActorAdmission = rosteredActorAdmission(),
+): CredentialHost {
+  let directory: CredentialDirectory | undefined
+  const bound = () => {
+    if (!directory) throw new Error("CredentialHost is not ready.")
+    return directory
+  }
+  return {
+    async ready(actors) {
+      directory = admission.bind(actors)
+      await provider.ready(directory)
+    },
+    async resolve(request) {
+      const authenticated = await provider.resolve(request)
+      if (!authenticated) {
+        return { type: "anonymous", signIn: provider.signIn }
+      }
+      const actor = await bound().admit(authenticated.identity)
+      return actor
+        ? {
+            type: "authenticated",
+            actor,
+            signOut: authenticated.signOut,
+          }
+        : { type: "anonymous", signIn: provider.signIn }
+    },
+    fetch(request) {
+      return provider.fetch(request, bound())
+    },
+    async close() {
+      await provider.close()
+      directory = undefined
+    },
+  }
+}
+
+const anonymousSession: CredentialSession = Object.freeze({
+  type: "anonymous",
+  signIn: null,
+})
+
+export function anonymousCredentialHost(): CredentialHost {
+  return {
+    async ready() {},
+    async resolve() {
+      return anonymousSession
+    },
+    async fetch() {
+      return new Response("Not Found", { status: 404 })
+    },
+    async close() {},
+  }
+}

package/authority/model.ts

@@ -0,0 +1,71 @@
+export type ActorProfile = Readonly<{
+  name: string
+  username: string
+  avatar?: string
+}>
+
+type ActorBase = Readonly<{
+  id: string
+  profile: ActorProfile
+  home: string
+}>
+
+// Actor should be a schema
+
+export type UserActor = ActorBase &
+  Readonly<{
+    type: "user"
+    role: "member" | "staff"
+  }>
+
+export type AgentActor = ActorBase & Readonly<{ type: "agent" }>
+
+export type Actor = UserActor | AgentActor
+
+export type Principal =
+  Readonly<{ type: "anonymous" }> | Readonly<{ type: "actor"; actor: Actor }>
+
+export type CredentialSession =
+  | Readonly<{
+      type: "anonymous"
+      signIn: Readonly<{ method: "get"; href: string }> | null
+    }>
+  | Readonly<{
+      type: "authenticated"
+      actor: UserActor
+      signOut: Readonly<{ method: "post"; href: string }> | null
+    }>
+
+export type ActorProfileRef = Readonly<{
+  id: string
+  profile: ActorProfile
+}>
+
+export type CredentialUser = Readonly<{
+  actor: UserActor
+  emails: readonly string[]
+}>
+
+export type ActorProfiles = Readonly<{
+  findById(id: string): ActorProfileRef | undefined
+  findByUsername(username: string): ActorProfileRef | undefined
+}>
+
+export type KnownActorIndex = ActorProfiles &
+  Readonly<{
+    findActorById(id: string): Actor | undefined
+    findHomeOwner(path: string): Actor | undefined
+    findUserByEmail(email: string): UserActor | undefined
+    credentialUsers(): readonly CredentialUser[]
+    all(): readonly Actor[]
+  }>
+
+export const anonymousPrincipal: Principal = Object.freeze({
+  type: "anonymous",
+})
+
+export function principalFor(session: CredentialSession): Principal {
+  return session.type === "authenticated"
+    ? { type: "actor", actor: session.actor }
+    : anonymousPrincipal
+}

package/authority/sharing.ts

@@ -0,0 +1,89 @@
+import { AccessDeniedError, type SharedSourceGrant } from "./access.ts"
+import { canonicalPath, canonicalSourceId } from "../canonical.ts"
+import type { Engine } from "../host/engine.ts"
+import { createSource, patchFrontmatter } from "../source/index.ts"
+import type { Actor } from "./model.ts"
+
+export function setSharedGrants(
+  engine: Engine,
+  actor: Actor,
+  sourceId: string,
+  grants: readonly SharedSourceGrant[],
+) {
+  canonicalSourceId(sourceId)
+  return engine.commitPrepared(async () => {
+    const before = engine.repo.get(sourceId)
+    if (!before) throw new AccessDeniedError()
+    const current = before.data.access
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      throw new AccessDeniedError("shared-source-required")
+    }
+    const owner = (current as Record<string, unknown>).owner
+    if (typeof owner !== "string") {
+      throw new AccessDeniedError("shared-source-required")
+    }
+    canonicalSourceId(owner)
+    const canonicalGrants = grants.map((grant) => ({
+      actor: canonicalSourceId(grant.actor),
+      can: [...grant.can],
+    }))
+    const canonicalActors = canonicalGrants.map((grant) => grant.actor)
+    if (new Set(canonicalActors).size !== canonicalActors.length) {
+      throw new AccessDeniedError("shared-members-must-be-unique")
+    }
+    const content = patchFrontmatter(
+      before.content,
+      { access: { type: "shared", owner, members: canonicalGrants } },
+      engine.environment.yaml,
+    )
+    const after = createSource(before.path, content, engine.environment.yaml)
+    const decision = engine.authorizeChange(actor, {
+      type: "update",
+      operation: "grants",
+      sourceId,
+      before,
+      after,
+    })
+    if (decision.type === "denied") throw new AccessDeniedError(decision.code)
+    return {
+      changes: [{ type: "replace" as const, path: before.path, content }],
+    }
+  })
+}
+
+export function setSourceAttachments(
+  engine: Engine,
+  actor: Actor,
+  sourceId: string,
+  attachments: readonly string[],
+) {
+  canonicalSourceId(sourceId)
+  const canonicalAttachments = attachments.map(canonicalPath)
+  if (
+    canonicalAttachments.some((attachment) => attachment.endsWith(".md")) ||
+    new Set(canonicalAttachments).size !== canonicalAttachments.length
+  ) {
+    throw new AccessDeniedError("invalid-attachment-binding")
+  }
+  return engine.commitPrepared(async () => {
+    const before = engine.repo.get(sourceId)
+    if (!before) throw new AccessDeniedError()
+    const content = patchFrontmatter(
+      before.content,
+      { attachments: canonicalAttachments },
+      engine.environment.yaml,
+    )
+    const after = createSource(before.path, content, engine.environment.yaml)
+    const decision = engine.authorizeChange(actor, {
+      type: "update",
+      operation: "attachments",
+      sourceId,
+      before,
+      after,
+    })
+    if (decision.type === "denied") throw new AccessDeniedError(decision.code)
+    return {
+      changes: [{ type: "replace" as const, path: before.path, content }],
+    }
+  })
+}