@sixb/core 0.1.7 → 0.1.9

package/src/storage/share-grants/record.ts

@@ -0,0 +1,347 @@
+import { createHash } from "node:crypto"
+import type { Principal } from "../../auth"
+import type { AuthorizablePrincipal } from "../../execution/types"
+import { stableJsonStringify } from "../../json"
+import type { ObjectRef } from "../../ontology"
+import { snapshotShareAccessPlan } from "../../shares/access-plan"
+import { ShareGrantStorageError } from "./errors"
+import type {
+  CreateShareGrantInput,
+  GetShareGrantByIdInput,
+  ListShareGrantsInput,
+  NormalizedListShareGrantsInput,
+  RevokeShareGrantInput,
+  ShareAuthoritySnapshot,
+  ShareGrantRecord,
+} from "./types"
+
+const DEFAULT_LIST_LIMIT = 50
+const MAX_LIST_LIMIT = 200
+const MAX_DESTINATION_PATH_LENGTH = 4_096
+const SHA256_HEX = /^[0-9a-f]{64}$/
+const SHARED_APP_PATH_PREFIX = "/shared"
+
+/** Normalize, detach, and derive every persisted field owned by Share grant storage. */
+export function normalizeShareGrantCreate(input: CreateShareGrantInput): ShareGrantRecord {
+  if (!isRecord(input)) throw invalidInput("Share grant create input must be an object.")
+  const projectId = identifier(input.projectId, "Project id")
+  const id = identifier(input.id, "Share grant id")
+  const definitionId = identifier(input.definitionId, "Share definition id")
+  const target = normalizeObjectRef(input.target, "Share target")
+  const issuedBy = normalizeAuthorizablePrincipal(input.issuedBy, "Share issuer")
+  const authoritySnapshot = normalizeAuthoritySnapshot(input.authoritySnapshot, target)
+  const tokenHash = sha256(input.tokenHash, "Share token hash")
+  const destinationPath = normalizeDestinationPath(input.destinationPath)
+  const createdAt = inputDate(input.createdAt, "Share creation time")
+  const expiresAt = inputDate(input.expiresAt, "Share expiry time")
+
+  if (expiresAt.getTime() <= createdAt.getTime()) {
+    throw invalidInput("Share expiry time must be later than creation time.")
+  }
+
+  return {
+    id,
+    projectId,
+    definitionId,
+    target,
+    issuedBy,
+    authoritySnapshot,
+    authorityDigest: shareAuthorityDigest(authoritySnapshot),
+    tokenHash,
+    destinationPath,
+    createdAt,
+    expiresAt,
+  }
+}
+
+/** Parse a provider row and reject unknown/corrupt durable authority instead of widening it. */
+export function parseShareGrantRecord(input: unknown): ShareGrantRecord {
+  if (!isRecord(input)) throw invalidRecord("Share grant row must be an object.")
+
+  try {
+    const projectId = identifier(input.projectId, "Project id")
+    const id = identifier(input.id, "Share grant id")
+    const definitionId = identifier(input.definitionId, "Share definition id")
+    const target = normalizeObjectRef(input.target, "Share target")
+    const issuedBy = normalizeAuthorizablePrincipal(input.issuedBy, "Share issuer")
+    const authoritySnapshot = normalizeAuthoritySnapshot(input.authoritySnapshot, target)
+    const authorityDigest = sha256(input.authorityDigest, "Share authority digest")
+    const expectedDigest = shareAuthorityDigest(authoritySnapshot)
+    if (authorityDigest !== expectedDigest) {
+      throw invalidRecord("Share authority digest does not match its snapshot.")
+    }
+    const tokenHash = sha256(input.tokenHash, "Share token hash")
+    const destinationPath = normalizeDestinationPath(input.destinationPath)
+    const createdAt = storedDate(input.createdAt, "Share creation time")
+    const expiresAt = storedDate(input.expiresAt, "Share expiry time")
+    if (expiresAt.getTime() <= createdAt.getTime()) {
+      throw invalidRecord("Share expiry time must be later than creation time.")
+    }
+
+    const revokedAtValue = input.revokedAt
+    const revokedByValue = input.revokedBy
+    if ((revokedAtValue === undefined) !== (revokedByValue === undefined)) {
+      throw invalidRecord("Share revocation time and actor must be stored together.")
+    }
+    if (revokedAtValue === null || revokedByValue === null) {
+      throw invalidRecord("Share revocation fields must be omitted rather than null.")
+    }
+
+    const revokedAt =
+      revokedAtValue === undefined ? undefined : storedDate(revokedAtValue, "Share revocation time")
+    const revokedBy =
+      revokedByValue === undefined
+        ? undefined
+        : normalizePrincipal(revokedByValue, "Share revocation actor")
+    if (revokedAt && revokedAt.getTime() < createdAt.getTime()) {
+      throw invalidRecord("Share revocation time must not precede creation time.")
+    }
+
+    return {
+      id,
+      projectId,
+      definitionId,
+      target,
+      issuedBy,
+      authoritySnapshot,
+      authorityDigest,
+      tokenHash,
+      destinationPath,
+      createdAt,
+      expiresAt,
+      ...(revokedAt === undefined ? {} : { revokedAt }),
+      ...(revokedBy === undefined ? {} : { revokedBy }),
+    }
+  } catch (error) {
+    if (error instanceof ShareGrantStorageError) {
+      if (error.code === "invalid_record") throw error
+      throw invalidRecord(error.message.replace(/^\[Sixb\] /, ""), error)
+    }
+    throw error
+  }
+}
+
+export function normalizeGetShareGrantByIdInput(
+  input: GetShareGrantByIdInput
+): GetShareGrantByIdInput {
+  if (!isRecord(input)) throw invalidInput("Share grant lookup input must be an object.")
+  return {
+    projectId: identifier(input.projectId, "Project id"),
+    id: identifier(input.id, "Share grant id"),
+  }
+}
+
+export function normalizeListShareGrantsInput(
+  input: ListShareGrantsInput
+): NormalizedListShareGrantsInput {
+  if (!isRecord(input)) throw invalidInput("Share grant list input must be an object.")
+  const projectId = identifier(input.projectId, "Project id")
+  const definitionId =
+    input.definitionId === undefined
+      ? undefined
+      : identifier(input.definitionId, "Share definition id")
+  const target =
+    input.target === undefined ? undefined : normalizeObjectRef(input.target, "Share target")
+  const includeRevoked = optionalBoolean(input.includeRevoked, "includeRevoked")
+  const includeExpired = optionalBoolean(input.includeExpired, "includeExpired")
+  const now = inputDate(input.now, "Share grant list time")
+  const limit = safeInteger(input.limit ?? DEFAULT_LIST_LIMIT, "Share grant list limit", 1)
+  const offset = safeInteger(input.offset ?? 0, "Share grant list offset", 0)
+  if (limit > MAX_LIST_LIMIT) {
+    throw invalidInput(`Share grant list limit must not exceed ${MAX_LIST_LIMIT}.`)
+  }
+
+  return {
+    projectId,
+    ...(definitionId === undefined ? {} : { definitionId }),
+    ...(target === undefined ? {} : { target }),
+    includeRevoked,
+    includeExpired,
+    now,
+    limit,
+    offset,
+  }
+}
+
+export function normalizeRevokeShareGrantInput(
+  input: RevokeShareGrantInput,
+  createdAt?: Date
+): RevokeShareGrantInput {
+  if (!isRecord(input)) throw invalidInput("Share grant revocation input must be an object.")
+  const normalized = {
+    projectId: identifier(input.projectId, "Project id"),
+    id: identifier(input.id, "Share grant id"),
+    revokedAt: inputDate(input.revokedAt, "Share revocation time"),
+    revokedBy: normalizePrincipal(input.revokedBy, "Share revocation actor"),
+  }
+  if (createdAt && normalized.revokedAt.getTime() < createdAt.getTime()) {
+    throw invalidInput("Share revocation time must not precede creation time.")
+  }
+  return normalized
+}
+
+export function cloneShareGrantRecord(input: ShareGrantRecord): ShareGrantRecord {
+  return structuredClone(input)
+}
+
+export function shareAuthorityDigest(snapshot: ShareAuthoritySnapshot): string {
+  return createHash("sha256").update(stableJsonStringify(snapshot)).digest("hex")
+}
+
+function normalizeAuthoritySnapshot(value: unknown, target: ObjectRef): ShareAuthoritySnapshot {
+  if (!isRecord(value) || value.version !== 1 || !isRecord(value.access)) {
+    throw invalidInput("Share authority snapshot version is unsupported.")
+  }
+  let access: ShareAuthoritySnapshot["access"]
+  try {
+    access = snapshotShareAccessPlan(value.access as never)
+  } catch (error) {
+    if (error instanceof ShareGrantStorageError) throw error
+    const reason = error instanceof Error ? error.message.replace(/^\[Sixb\] /, "") : String(error)
+    throw invalidInput(`Share authority snapshot is invalid: ${reason}`, error)
+  }
+  assertAccessTargets(access, target)
+  return Object.freeze({ version: 1, access })
+}
+
+function assertAccessTargets(access: ShareAuthoritySnapshot["access"], target: ObjectRef): void {
+  for (const grant of access.grants) {
+    if (grant.kind === "object.view") {
+      for (const root of grant.selection.roots) {
+        if (!sameObjectRef(root.anchor, target)) {
+          throw invalidInput("Every Share view root must match the exact Share target.")
+        }
+      }
+      continue
+    }
+    for (const subject of grant.subjects) {
+      if (!sameObjectRef(subject, target)) {
+        throw invalidInput("Every shared Action subject must match the exact Share target.")
+      }
+    }
+  }
+}
+
+function sameObjectRef(left: ObjectRef, right: ObjectRef): boolean {
+  return left.objectTypeId === right.objectTypeId && left.primaryId === right.primaryId
+}
+
+function normalizeObjectRef(value: unknown, label: string): ObjectRef {
+  if (!isRecord(value)) throw invalidInput(`${label} must be an exact object reference.`)
+  return Object.freeze({
+    objectTypeId: identifier(value.objectTypeId, `${label} object type id`),
+    primaryId: identifier(value.primaryId, `${label} primary id`),
+  })
+}
+
+function normalizeAuthorizablePrincipal(value: unknown, label: string): AuthorizablePrincipal {
+  const principal = normalizePrincipal(value, label)
+  if (principal.type === "system") {
+    throw invalidInput(`${label} must be a user or service account.`)
+  }
+  return principal
+}
+
+function normalizePrincipal(value: unknown, label: string): Principal {
+  if (!isRecord(value)) throw invalidInput(`${label} must be a principal.`)
+  if (value.type !== "user" && value.type !== "serviceAccount" && value.type !== "system") {
+    throw invalidInput(`${label} has an unsupported type.`)
+  }
+  return Object.freeze({ type: value.type, id: identifier(value.id, `${label} id`) })
+}
+
+function normalizeDestinationPath(value: unknown): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw invalidInput("Share destination path must not be empty.")
+  }
+  if (value.length > MAX_DESTINATION_PATH_LENGTH) {
+    throw invalidInput(
+      `Share destination path must not exceed ${MAX_DESTINATION_PATH_LENGTH} characters.`
+    )
+  }
+  if (
+    !value.startsWith("/") ||
+    value.includes("//") ||
+    value.includes("?") ||
+    value.includes("#") ||
+    value.includes("\\") ||
+    value.includes("\0")
+  ) {
+    throw invalidInput(
+      "Share destination path must be an absolute same-origin pathname without query or fragment."
+    )
+  }
+  const normalized = new URL(value, "https://sixb.invalid").pathname
+  if (normalized !== value) {
+    throw invalidInput("Share destination path must already be canonical.")
+  }
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(value).replaceAll("\\", "/")
+  } catch {
+    throw invalidInput("Share destination path must contain valid percent-encoding.")
+  }
+  if (decoded === SHARED_APP_PATH_PREFIX || decoded.startsWith(`${SHARED_APP_PATH_PREFIX}/`)) {
+    throw invalidInput(
+      "Share destination path must not use the framework-owned '/shared' namespace."
+    )
+  }
+  return value
+}
+
+function identifier(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
+    throw invalidInput(`${label} must be a non-empty string without NUL bytes.`)
+  }
+  return value
+}
+
+function sha256(value: unknown, label: string): string {
+  if (typeof value !== "string" || !SHA256_HEX.test(value)) {
+    throw invalidInput(`${label} must be a lowercase SHA-256 hex digest.`)
+  }
+  return value
+}
+
+function inputDate(value: unknown, label: string): Date {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw invalidInput(`${label} must be a valid Date.`)
+  }
+  return new Date(value)
+}
+
+function storedDate(value: unknown, label: string): Date {
+  const parsed =
+    value instanceof Date
+      ? new Date(value)
+      : typeof value === "string"
+        ? new Date(value)
+        : new Date(Number.NaN)
+  if (!Number.isFinite(parsed.getTime())) throw invalidRecord(`${label} is invalid.`)
+  return parsed
+}
+
+function optionalBoolean(value: unknown, label: string): boolean {
+  if (value === undefined) return false
+  if (typeof value !== "boolean") throw invalidInput(`${label} must be a boolean.`)
+  return value
+}
+
+function safeInteger(value: unknown, label: string, minimum: number): number {
+  if (!Number.isSafeInteger(value) || (value as number) < minimum) {
+    throw invalidInput(`${label} must be a safe integer greater than or equal to ${minimum}.`)
+  }
+  return value as number
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function invalidInput(message: string, cause?: unknown): ShareGrantStorageError {
+  return new ShareGrantStorageError("invalid_input", `[Sixb] ${message}`, { cause })
+}
+
+function invalidRecord(message: string, cause?: unknown): ShareGrantStorageError {
+  return new ShareGrantStorageError("invalid_record", `[Sixb] ${message}`, { cause })
+}

package/src/storage/share-grants/types.ts

@@ -0,0 +1,112 @@
+import type { Principal } from "../../auth"
+import type { AuthorizablePrincipal } from "../../execution/types"
+import type { ObjectRef } from "../../ontology"
+import type { ShareAccessPlan } from "../../shares/access-plan"
+
+/** First durable encoding of the exact authority captured when a Share is issued. */
+export interface ShareAuthoritySnapshotV1 {
+  readonly version: 1
+  readonly access: ShareAccessPlan
+}
+
+/** Versioned so persisted grants can fail closed when a future encoding is introduced. */
+export type ShareAuthoritySnapshot = ShareAuthoritySnapshotV1
+
+/** Durable audit and authority record for one issued Share link. */
+export interface ShareGrantRecord {
+  readonly id: string
+  readonly projectId: string
+  readonly definitionId: string
+  readonly target: ObjectRef
+  /** Audit attribution only. The issuer never contributes ambient authority to the Share. */
+  readonly issuedBy: AuthorizablePrincipal
+  readonly authoritySnapshot: ShareAuthoritySnapshot
+  /** SHA-256 of the canonical authority snapshot. */
+  readonly authorityDigest: string
+  /** SHA-256 of the one-time link secret. The plaintext secret is never durable. */
+  readonly tokenHash: string
+  readonly destinationPath: string
+  readonly createdAt: Date
+  readonly expiresAt: Date
+  readonly revokedAt?: Date
+  readonly revokedBy?: Principal
+}
+
+/** Create input omits fields derived by storage or written only by revocation. */
+export type CreateShareGrantInput = Omit<
+  ShareGrantRecord,
+  "authorityDigest" | "revokedAt" | "revokedBy"
+>
+
+export interface GetShareGrantByIdInput {
+  readonly projectId: string
+  readonly id: string
+}
+
+export interface ListShareGrantsInput {
+  readonly projectId: string
+  readonly definitionId?: string
+  readonly target?: ObjectRef
+  readonly includeRevoked?: boolean
+  readonly includeExpired?: boolean
+  /** Explicit clock keeps expiry semantics deterministic across providers. */
+  readonly now: Date
+  readonly limit?: number
+  readonly offset?: number
+}
+
+export interface NormalizedListShareGrantsInput {
+  readonly projectId: string
+  readonly definitionId?: string
+  readonly target?: ObjectRef
+  readonly includeRevoked: boolean
+  readonly includeExpired: boolean
+  readonly now: Date
+  readonly limit: number
+  readonly offset: number
+}
+
+export interface ListShareGrantsResult {
+  readonly grants: readonly ShareGrantRecord[]
+  /** Matching rows before offset/limit are applied. */
+  readonly total: number
+  /** True when at least one matching row remains after this page. */
+  readonly hasMore: boolean
+}
+
+export interface RevokeShareGrantInput {
+  readonly projectId: string
+  readonly id: string
+  readonly revokedAt: Date
+  readonly revokedBy: Principal
+}
+
+/**
+ * Persistence only. Secret generation, verification, and current-definition intersection are
+ * Core. Every returned record must be detached from provider state; deeply immutable records also
+ * satisfy that isolation contract.
+ */
+export interface ShareGrantStorage {
+  /**
+   * Persist a normalized grant, deriving `authorityDigest`. The `(projectId, id)` and
+   * `(projectId, tokenHash)` pairs must both be unique; either collision reports `duplicate`.
+   */
+  create(input: CreateShareGrantInput): Promise<ShareGrantRecord>
+
+  /** Load one project-scoped grant, including expired or revoked grants, or return null. */
+  getById(input: GetShareGrantByIdInput): Promise<ShareGrantRecord | null>
+
+  /**
+   * List in deterministic `createdAt DESC, id DESC` order. Expired and revoked rows are excluded
+   * unless requested; `total` is computed after filtering and before pagination. A root call may
+   * be weakly consistent with concurrent writes; callers that need one snapshot use
+   * `Storage.transaction`.
+   */
+  list(input: ListShareGrantsInput): Promise<ListShareGrantsResult>
+
+  /**
+   * Atomically preserve the first revocation. Repeating a revocation returns that first record;
+   * a missing grant returns null.
+   */
+  revoke(input: RevokeShareGrantInput): Promise<ShareGrantRecord | null>
+}

package/src/storage/share-sessions/errors.ts

@@ -0,0 +1,14 @@
+export type ShareSessionStorageErrorCode = "duplicate" | "invalid_input" | "invalid_record"
+
+/** Provider-level control signal for durable Share session persistence. */
+export class ShareSessionStorageError extends Error {
+  readonly name = "ShareSessionStorageError"
+
+  constructor(
+    readonly code: ShareSessionStorageErrorCode,
+    message: string,
+    options?: ErrorOptions
+  ) {
+    super(message, options)
+  }
+}

package/src/storage/share-sessions/in-memory.ts

@@ -0,0 +1,105 @@
+import type { ShareGrantStorage } from "../share-grants"
+import { ShareSessionStorageError } from "./errors"
+import {
+  cloneShareSessionRecord,
+  normalizeGetShareSessionByIdInput,
+  normalizeRenewShareSessionIfValidInput,
+  normalizeRevokeShareSessionInput,
+  normalizeShareSessionCreate,
+  parseShareSessionRecord,
+} from "./record"
+import type {
+  CreateShareSessionInput,
+  GetShareSessionByIdInput,
+  RenewShareSessionIfValidInput,
+  RevokeShareSessionInput,
+  ShareSessionRecord,
+  ShareSessionStorage,
+} from "./types"
+
+export class InMemoryShareSessionStorage implements ShareSessionStorage {
+  private rows = new Map<string, ShareSessionRecord>()
+
+  constructor(private readonly grants: Pick<ShareGrantStorage, "getById">) {}
+
+  async create(input: CreateShareSessionInput): Promise<ShareSessionRecord> {
+    const record = normalizeShareSessionCreate(input)
+    const grant = await this.grants.getById({ projectId: record.projectId, id: record.grantId })
+    if (!grant) {
+      throw new ShareSessionStorageError(
+        "invalid_input",
+        `[Sixb] Share grant '${record.grantId}' does not exist in project '${record.projectId}'.`
+      )
+    }
+    const key = rowKey(record.projectId, record.id)
+    const duplicateTokenHash = [...this.rows.values()].some(
+      (current) => current.projectId === record.projectId && current.tokenHash === record.tokenHash
+    )
+    if (this.rows.has(key) || duplicateTokenHash) {
+      throw new ShareSessionStorageError(
+        "duplicate",
+        `[Sixb] Share session '${record.id}' conflicts with an existing record.`
+      )
+    }
+    this.rows.set(key, record)
+    return cloneShareSessionRecord(record)
+  }
+
+  async getById(input: GetShareSessionByIdInput): Promise<ShareSessionRecord | null> {
+    const normalized = normalizeGetShareSessionByIdInput(input)
+    const record = this.rows.get(rowKey(normalized.projectId, normalized.id))
+    return record ? cloneShareSessionRecord(record) : null
+  }
+
+  async renewIfValid(input: RenewShareSessionIfValidInput): Promise<ShareSessionRecord | null> {
+    const normalized = normalizeRenewShareSessionIfValidInput(input)
+    const key = rowKey(normalized.projectId, normalized.id)
+    const current = this.rows.get(key)
+    if (
+      !current ||
+      current.grantId !== normalized.grantId ||
+      current.tokenHash !== normalized.tokenHash ||
+      current.revokedAt !== undefined ||
+      current.createdAt.getTime() > normalized.now.getTime() ||
+      current.expiresAt.getTime() <= normalized.now.getTime() ||
+      current.absoluteExpiresAt.getTime() <= normalized.now.getTime()
+    ) {
+      return null
+    }
+
+    const nextExpiry = Math.min(
+      current.absoluteExpiresAt.getTime(),
+      Math.max(current.expiresAt.getTime(), normalized.expiresAt.getTime())
+    )
+    const updated = { ...current, expiresAt: new Date(nextExpiry) }
+    this.rows.set(key, updated)
+    return cloneShareSessionRecord(updated)
+  }
+
+  async revoke(input: RevokeShareSessionInput): Promise<ShareSessionRecord | null> {
+    const normalized = normalizeRevokeShareSessionInput(input)
+    const key = rowKey(normalized.projectId, normalized.id)
+    const current = this.rows.get(key)
+    if (!current) return null
+    if (current.revokedAt) return cloneShareSessionRecord(current)
+
+    const revocation = normalizeRevokeShareSessionInput(normalized, current.createdAt)
+    const updated = { ...current, revokedAt: new Date(revocation.revokedAt) }
+    this.rows.set(key, updated)
+    return cloneShareSessionRecord(updated)
+  }
+
+  snapshot(): ReadonlyMap<string, ShareSessionRecord> {
+    return new Map([...this.rows].map(([key, record]) => [key, cloneShareSessionRecord(record)]))
+  }
+
+  restore(snapshot: ReadonlyMap<string, ShareSessionRecord>): void {
+    this.rows = new Map(
+      [...snapshot].map(([key, record]) => [key, parseShareSessionRecord(record)])
+    )
+  }
+}
+
+function rowKey(projectId: string, id: string): string {
+  return `${projectId}\0${id}`
+}

package/src/storage/share-sessions/index.ts

@@ -0,0 +1,11 @@
+export type { ShareSessionStorageErrorCode } from "./errors"
+export { ShareSessionStorageError } from "./errors"
+export { InMemoryShareSessionStorage } from "./in-memory"
+export type {
+  CreateShareSessionInput,
+  GetShareSessionByIdInput,
+  RenewShareSessionIfValidInput,
+  RevokeShareSessionInput,
+  ShareSessionRecord,
+  ShareSessionStorage,
+} from "./types"

package/src/storage/share-sessions/provider.ts

@@ -0,0 +1,9 @@
+/** @internal Repository storage-provider helpers; not part of the app-author API. */
+export {
+  cloneShareSessionRecord,
+  normalizeGetShareSessionByIdInput,
+  normalizeRenewShareSessionIfValidInput,
+  normalizeRevokeShareSessionInput,
+  normalizeShareSessionCreate,
+  parseShareSessionRecord,
+} from "./record"