feat(supabase): V1-2.1 M4/M5 secure sheet access and review workflow

M4 20261028100000_sheet_access_hardening + M5 20261028110000_sheet_review_workflow
(applied together; no unprotected window). Implements contract §5-§14.

- Catalogue rights table + owner RPCs; has_mfa / has_aal2_session (live
  auth.sessions check); grant_active vs caller_has split; catalogue reader
  predicate; can_edit_sheet on the sheet_editor capability (F14).
- AR-1 B: aal2 required on every platform role change, target verified factor,
  race-free last-owner guard (F18/F19); service_role loses table privileges on
  the catalogue + profiles/profile_roles and EXECUTE on the role RPCs (F12/F17).
- Reviewed lifecycle: version provenance + review columns, content/freeze/
  author triggers, rounds/comments/acknowledgments, save/submit/withdraw/
  comment/acknowledge/decide, atomic publish_sheet_version(review_id) on the
  stored verdict, deprecate/archive/restore, species RPCs, equine working copy,
  uploads with the storage check (F7) + editor INSERT policy + 2 MiB bucket.
  F1-F3,F5,F6,F8,F9,F13,F15,F16 closed. Verdict is a fixture until M6 (V1-2.3).
- O22: SQL business mirror removed, declared status check kept; pgTAP 011 and
  the Rust generator's SQL parts deleted, ledger retargeted.
- Access layer sheets.ts (closed SheetFailure kinds); old client publish gate
  deleted; types regenerated; upload tool reads via get_sheet_asset_state.

Tested on the throwaway sandbox only; DEV untouched. pgTAP 850 (real stack) /
122 (PGlite) green; real-GoTrue AR-1 B + F18 race green; fresh install and
M3->M5 upgrade green; V1-1 regression green; rust:check, typecheck, lint,
build, types drift clean. BDR-084, LRN-095.
This commit is contained in:
bchanot committed 2026-10-28 15:52:49 +01:00
1 parent 9c13bae4bc
commit 77e5fa4cf5
33 files changed
+4613 -1617

No files matched your search

-105
View File
@@ -1,105 +0,0 @@
import type { FaunosteoClient } from './client'
/**
* Publication gate on the client side: the full shape and every integrity
* rule run before the RPC, so the editor gets the complete issue list. The
* rules run in the Rust core (R2): the caller passes its `sheet.check`
* operation, so this package never loads the module itself. The gate fails
* closed: anything but a publishable verdict refuses publication. The
* database re-checks the referential rules on its own
* (private.sheet_document_issues); this call never replaces that guard.
*/
export interface SheetIssue {
code: string
severity: 'error' | 'warning'
path: string
message: string
}
/** The core's verdict on a document (`sheet.check`), or why it could not give one. */
export type SheetCheckOutcome =
| { ok: true; value: { issues: SheetIssue[]; publishable: boolean } }
| { ok: false; kind: string; detail?: string }
export type SheetValidator = (content: unknown) => SheetCheckOutcome
export type SheetPublishErrorKind =
/**
* The document does not match the strict schema, or carries a text the core cannot read
* without altering it (`lone_surrogate`).
*/
| 'invalid_shape'
/** Integrity errors (warnings never block). */
| 'not_publishable'
/** The validator could not run (core unavailable, trap): publication refused. */
| 'validator_unavailable'
export class SheetPublishError extends Error {
constructor(
readonly kind: SheetPublishErrorKind,
readonly issues: SheetIssue[] = [],
detail = '',
) {
super(SheetPublishError.messageOf(kind, issues, detail))
this.name = 'SheetPublishError'
}
private static messageOf(
kind: SheetPublishErrorKind,
issues: SheetIssue[],
detail: string,
): string {
if (kind === 'not_publishable') {
const errors = issues.filter((issue) => issue.severity === 'error')
return (
`Sheet document is not publishable: ${errors.length} error(s), ` +
`first: ${errors[0]?.code ?? 'none'}`
)
}
if (kind === 'invalid_shape') {
return `Sheet document does not match the schema${detail ? `: ${detail}` : ''}`
}
return `Sheet validator unavailable${detail ? ` (${detail})` : ''}`
}
}
/** The validator's kinds that judge the document itself, not the validator's state. */
const CONTENT_KINDS: ReadonlySet<string> = new Set([
'invalid_shape',
'lone_surrogate',
])
/** Throws unless the validator says the document is publishable. */
function assertPublishable(validate: SheetValidator, content: unknown): void {
const check = validate(content)
if (!check.ok) {
throw CONTENT_KINDS.has(check.kind)
? new SheetPublishError('invalid_shape', [], check.detail)
: new SheetPublishError('validator_unavailable', [], check.kind)
}
if (!check.value.publishable) {
throw new SheetPublishError('not_publishable', check.value.issues)
}
}
export async function publishSheetVersion(
client: FaunosteoClient,
versionId: string,
validate: SheetValidator,
): Promise<string> {
const draft = await client
.from('anatomical_sheet_versions')
.select('content')
.eq('id', versionId)
.single()
if (draft.error) throw draft.error
assertPublishable(validate, draft.data.content)
const published = await client.rpc('publish_sheet_version', {
version_id: versionId,
})
if (published.error) throw published.error
return published.data
}
+410 -23
View File
@@ -9,6 +9,71 @@ export type Json =
export type Database = {
public: {
Tables: {
anatomical_catalog_grants: {
Row: {
expires_at: string | null
grant_kind: Database['public']['Enums']['catalog_grant_kind']
granted_at: string
granted_by: string
id: string
reason: string
revocation_reason: string | null
revoked_at: string | null
revoked_by: string | null
user_id: string
verification_note: string | null
}
ComputedFields: never
Insert: {
expires_at?: string | null
grant_kind: Database['public']['Enums']['catalog_grant_kind']
granted_at?: string
granted_by: string
id?: string
reason: string
revocation_reason?: string | null
revoked_at?: string | null
revoked_by?: string | null
user_id: string
verification_note?: string | null
}
Update: {
expires_at?: string | null
grant_kind?: Database['public']['Enums']['catalog_grant_kind']
granted_at?: string
granted_by?: string
id?: string
reason?: string
revocation_reason?: string | null
revoked_at?: string | null
revoked_by?: string | null
user_id?: string
verification_note?: string | null
}
Relationships: [
{
foreignKeyName: 'anatomical_catalog_grants_granted_by_fkey'
columns: ['granted_by']
isOneToOne: false
referencedRelation: 'profiles'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_catalog_grants_revoked_by_fkey'
columns: ['revoked_by']
isOneToOne: false
referencedRelation: 'profiles'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_catalog_grants_user_id_fkey'
columns: ['user_id']
isOneToOne: false
referencedRelation: 'profiles'
referencedColumns: ['id']
},
]
}
anatomical_sheet_assets: {
Row: {
byte_size: number
@@ -61,52 +126,270 @@ export type Database = {
},
]
}
anatomical_sheet_review_acknowledgments: {
Row: {
created_at: string
group_digest: string
group_key: string
id: string
review_id: string
reviewer: string
}
ComputedFields: never
Insert: {
created_at?: string
group_digest: string
group_key: string
id?: string
review_id: string
reviewer: string
}
Update: {
created_at?: string
group_digest?: string
group_key?: string
id?: string
review_id?: string
reviewer?: string
}
Relationships: [
{
foreignKeyName: 'anatomical_sheet_review_acknowledgments_review_id_fkey'
columns: ['review_id']
isOneToOne: false
referencedRelation: 'anatomical_sheet_reviews'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_sheet_review_acknowledgments_reviewer_fkey'
columns: ['reviewer']
isOneToOne: false
referencedRelation: 'profiles'
referencedColumns: ['id']
},
]
}
anatomical_sheet_review_comments: {
Row: {
author: string
body: string
created_at: string
group_key: string | null
id: string
review_id: string
}
ComputedFields: never
Insert: {
author: string
body: string
created_at?: string
group_key?: string | null
id?: string
review_id: string
}
Update: {
author?: string
body?: string
created_at?: string
group_key?: string | null
id?: string
review_id?: string
}
Relationships: [
{
foreignKeyName: 'anatomical_sheet_review_comments_author_fkey'
columns: ['author']
isOneToOne: false
referencedRelation: 'profiles'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_sheet_review_comments_review_id_fkey'
columns: ['review_id']
isOneToOne: false
referencedRelation: 'anatomical_sheet_reviews'
referencedColumns: ['id']
},
]
}
anatomical_sheet_reviews: {
Row: {
attempts: number
authors: string[]
created_at: string
decided_at: string | null
decided_by: string | null
decision_note: string | null
failure_code: string | null
failure_outcome:
| Database['public']['Enums']['sheet_verification_outcome']
| null
id: string
lease_token: string | null
locked_at: string | null
revision: number
round: number
status: Database['public']['Enums']['sheet_round_status']
submission_note: string | null
submitted_at: string
submitted_by: string
verdict: Json | null
verified_at: string | null
verified_with: string | null
version_id: string
withdrawal_note: string | null
withdrawn_at: string | null
withdrawn_by: string | null
}
ComputedFields: never
Insert: {
attempts?: number
authors: string[]
created_at?: string
decided_at?: string | null
decided_by?: string | null
decision_note?: string | null
failure_code?: string | null
failure_outcome?:
| Database['public']['Enums']['sheet_verification_outcome']
| null
id?: string
lease_token?: string | null
locked_at?: string | null
revision: number
round: number
status?: Database['public']['Enums']['sheet_round_status']
submission_note?: string | null
submitted_at?: string
submitted_by: string
verdict?: Json | null
verified_at?: string | null
verified_with?: string | null
version_id: string
withdrawal_note?: string | null
withdrawn_at?: string | null
withdrawn_by?: string | null
}
Update: {
attempts?: number
authors?: string[]
created_at?: string
decided_at?: string | null
decided_by?: string | null
decision_note?: string | null
failure_code?: string | null
failure_outcome?:
| Database['public']['Enums']['sheet_verification_outcome']
| null
id?: string
lease_token?: string | null
locked_at?: string | null
revision?: number
round?: number
status?: Database['public']['Enums']['sheet_round_status']
submission_note?: string | null
submitted_at?: string
submitted_by?: string
verdict?: Json | null
verified_at?: string | null
verified_with?: string | null
version_id?: string
withdrawal_note?: string | null
withdrawn_at?: string | null
withdrawn_by?: string | null
}
Relationships: [
{
foreignKeyName: 'anatomical_sheet_reviews_decided_by_fkey'
columns: ['decided_by']
isOneToOne: false
referencedRelation: 'profiles'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_sheet_reviews_submitted_by_fkey'
columns: ['submitted_by']
isOneToOne: false
referencedRelation: 'profiles'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_sheet_reviews_version_id_fkey'
columns: ['version_id']
isOneToOne: false
referencedRelation: 'anatomical_sheet_versions'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_sheet_reviews_withdrawn_by_fkey'
columns: ['withdrawn_by']
isOneToOne: false
referencedRelation: 'profiles'
referencedColumns: ['id']
},
]
}
anatomical_sheet_versions: {
Row: {
authors: string[]
change_note: string
content: NonNullable<Json>
created_at: string
created_by: string | null
deprecated_at: string | null
deprecated_by: string | null
document_fingerprint: string | null
document_schema_version: number
id: string
published_at: string | null
published_by: string | null
published_review_id: string | null
revision: number
sheet_id: string
source_version_id: string | null
status: Database['public']['Enums']['sheet_version_status']
updated_at: string
version_number: number
}
ComputedFields: never
Insert: {
authors?: string[]
change_note?: string
content: NonNullable<Json>
created_at?: string
created_by?: string | null
deprecated_at?: string | null
deprecated_by?: string | null
document_fingerprint?: string | null
document_schema_version: number
id?: string
published_at?: string | null
published_by?: string | null
published_review_id?: string | null
revision?: number
sheet_id: string
source_version_id?: string | null
status?: Database['public']['Enums']['sheet_version_status']
updated_at?: string
version_number: number
}
Update: {
authors?: string[]
change_note?: string
content?: NonNullable<Json>
created_at?: string
created_by?: string | null
deprecated_at?: string | null
deprecated_by?: string | null
document_fingerprint?: string | null
document_schema_version?: number
id?: string
published_at?: string | null
published_by?: string | null
published_review_id?: string | null
revision?: number
sheet_id?: string
source_version_id?: string | null
status?: Database['public']['Enums']['sheet_version_status']
updated_at?: string
version_number?: number
@@ -133,6 +416,13 @@ export type Database = {
referencedRelation: 'profiles'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_sheet_versions_published_review_fkey'
columns: ['published_review_id']
isOneToOne: false
referencedRelation: 'anatomical_sheet_reviews'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_sheet_versions_sheet_id_fkey'
columns: ['sheet_id']
@@ -140,6 +430,13 @@ export type Database = {
referencedRelation: 'anatomical_sheets'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_sheet_versions_source_version_id_fkey'
columns: ['source_version_id']
isOneToOne: false
referencedRelation: 'anatomical_sheet_versions'
referencedColumns: ['id']
},
]
}
anatomical_sheets: {
@@ -161,6 +458,7 @@ export type Database = {
status: Database['public']['Enums']['sheet_status']
updated_at: string
visibility: Database['public']['Enums']['sheet_visibility']
working_copy_source_version_id: string | null
}
ComputedFields: never
Insert: {
@@ -181,6 +479,7 @@ export type Database = {
status?: Database['public']['Enums']['sheet_status']
updated_at?: string
visibility?: Database['public']['Enums']['sheet_visibility']
working_copy_source_version_id?: string | null
}
Update: {
archived_at?: string | null
@@ -200,6 +499,7 @@ export type Database = {
status?: Database['public']['Enums']['sheet_status']
updated_at?: string
visibility?: Database['public']['Enums']['sheet_visibility']
working_copy_source_version_id?: string | null
}
Relationships: [
{
@@ -237,6 +537,13 @@ export type Database = {
referencedRelation: 'species'
referencedColumns: ['id']
},
{
foreignKeyName: 'anatomical_sheets_working_copy_source_version_id_fkey'
columns: ['working_copy_source_version_id']
isOneToOne: false
referencedRelation: 'anatomical_sheet_versions'
referencedColumns: ['id']
},
]
}
animal_client_relations: {
@@ -738,6 +1045,11 @@ export type Database = {
}
Functions: {
ack_purge: { Args: { purge_id: string }; Returns: undefined }
acknowledge_sheet_review_group: {
Args: { group_digest: string; group_key: string; review_id: string }
Returns: string
}
activate_species: { Args: { id: string }; Returns: string }
archive_anatomical_sheet: { Args: { sheet_id: string }; Returns: string }
begin_avatar_upload: {
Args: { declared_mime: string; declared_size: number }
@@ -772,6 +1084,10 @@ export type Database = {
}[]
}
client_archive_preview: { Args: { client_id: string }; Returns: Json }
comment_sheet_review: {
Args: { body: string; group_key?: string; review_id: string }
Returns: string
}
complete_avatar_job: {
Args: {
asset_id: string
@@ -786,18 +1102,6 @@ export type Database = {
Args: { asset_id: string }
Returns: string
}
create_anatomical_sheet: {
Args: {
description?: string
document: Json
name: string
official?: boolean
slug: string
species_id: string
visibility?: Database['public']['Enums']['sheet_visibility']
}
Returns: string
}
create_animal: {
Args: {
birth_date?: string
@@ -841,6 +1145,10 @@ export type Database = {
}
Returns: Json
}
create_official_sheet: {
Args: { document: Json; slug: string }
Returns: string
}
create_sheet_draft: {
Args: {
change_note?: string
@@ -849,6 +1157,23 @@ export type Database = {
}
Returns: string
}
create_sheet_working_copy: {
Args: { slug: string; source_version_id: string }
Returns: string
}
create_species: {
Args: {
id: string
name_en: string
name_fr: string
sort_order?: number
}
Returns: string
}
decide_sheet_review: {
Args: { approve: boolean; note: string; review_id: string }
Returns: string
}
delete_anatomical_sheet: { Args: { sheet_id: string }; Returns: string }
delete_sheet_asset: { Args: { asset_id: string }; Returns: string }
delete_sheet_version: { Args: { version_id: string }; Returns: string }
@@ -868,12 +1193,15 @@ export type Database = {
Args: { max_age_seconds: number }
Returns: number
}
fork_anatomical_sheet: {
get_sheet_asset_state: { Args: { asset_id: string }; Returns: Json }
get_sheet_version: { Args: { version_id: string }; Returns: Json }
grant_catalog_right: {
Args: {
name: string
slug: string
source_version_id: string
visibility?: Database['public']['Enums']['sheet_visibility']
expires_at?: string
kind: Database['public']['Enums']['catalog_grant_kind']
reason: string
user_id: string
verification_note?: string
}
Returns: string
}
@@ -884,6 +1212,8 @@ export type Database = {
}
Returns: string
}
list_catalog_grants: { Args: Record<PropertyKey, never>; Returns: Json }
list_catalog_species: { Args: Record<PropertyKey, never>; Returns: Json }
list_client_animals: {
Args: {
after_id?: string
@@ -909,8 +1239,10 @@ export type Database = {
started_on: string
}[]
}
list_official_catalog: { Args: Record<PropertyKey, never>; Returns: Json }
lookup_catalog_account: { Args: { email: string }; Returns: Json }
mark_quarantine_purged: { Args: { asset_id: string }; Returns: undefined }
publish_sheet_version: { Args: { version_id: string }; Returns: string }
publish_sheet_version: { Args: { review_id: string }; Returns: string }
register_sheet_asset: {
Args: {
byte_size: number
@@ -925,7 +1257,15 @@ export type Database = {
Returns: undefined
}
remove_avatar: { Args: Record<PropertyKey, never>; Returns: number }
rename_species: {
Args: { id: string; name_en: string; name_fr: string }
Returns: string
}
restore_anatomical_sheet: { Args: { sheet_id: string }; Returns: string }
revoke_catalog_right: {
Args: { grant_id: string; reason: string }
Returns: string
}
revoke_platform_role: {
Args: {
reason?: string
@@ -934,6 +1274,15 @@ export type Database = {
}
Returns: string
}
save_sheet_draft: {
Args: {
change_note?: string
document: Json
expected_revision: number
version_id: string
}
Returns: Json
}
search_animals: {
Args: {
after_id?: string
@@ -987,11 +1336,8 @@ export type Database = {
Args: { archived: boolean; client_id: string }
Returns: Json
}
set_sheet_visibility: {
Args: {
sheet_id: string
visibility: Database['public']['Enums']['sheet_visibility']
}
submit_sheet_review: {
Args: { expected_revision: number; note?: string; version_id: string }
Returns: string
}
update_animal: {
@@ -1033,10 +1379,23 @@ export type Database = {
}
Returns: Json
}
update_inactive_species: {
Args: {
id: string
name_en: string
name_fr: string
sort_order: number
}
Returns: string
}
void_animal_client_relation: {
Args: { expected_revision: number; relation_id: string }
Returns: Json
}
withdraw_sheet_review: {
Args: { note?: string; review_id: string }
Returns: string
}
}
Enums: {
animal_relation_role: 'owner' | 'keeper' | 'contact'
@@ -1047,9 +1406,22 @@ export type Database = {
| 'clean'
| 'rejected'
| 'deleted'
catalog_grant_kind:
| 'catalog_reader'
| 'sheet_editor'
| 'sheet_reviewer'
| 'sheet_publisher'
client_kind: 'person' | 'organization'
platform_role: 'owner' | 'admin' | 'moderator' | 'support'
sheet_round_status:
| 'verifying'
| 'open'
| 'approved'
| 'changes_requested'
| 'withdrawn'
| 'verification_failed'
sheet_status: 'active' | 'archived' | 'deleted'
sheet_verification_outcome: 'failed' | 'unavailable'
sheet_version_status: 'draft' | 'published' | 'deprecated'
sheet_visibility: 'private' | 'public'
workspace_kind: 'personal'
@@ -1190,9 +1562,24 @@ export const Constants = {
'rejected',
'deleted',
],
catalog_grant_kind: [
'catalog_reader',
'sheet_editor',
'sheet_reviewer',
'sheet_publisher',
],
client_kind: ['person', 'organization'],
platform_role: ['owner', 'admin', 'moderator', 'support'],
sheet_round_status: [
'verifying',
'open',
'approved',
'changes_requested',
'withdrawn',
'verification_failed',
],
sheet_status: ['active', 'archived', 'deleted'],
sheet_verification_outcome: ['failed', 'unavailable'],
sheet_version_status: ['draft', 'published', 'deprecated'],
sheet_visibility: ['private', 'public'],
workspace_kind: ['personal'],
+15 -6
View File
@@ -44,13 +44,22 @@ export {
/** owner | admin | moderator | support. Not a professional status. */
export { fetchOwnPlatformRoles, type PlatformRole } from './platform-roles'
export {
SHEET_FAILURE_KINDS,
SheetFailure,
classifySheetError,
failSheet,
grantCatalogRight,
revokeCatalogRight,
listCatalogGrants,
createOfficialSheet,
saveSheetDraft,
submitSheetReview,
decideSheetReview,
publishSheetVersion,
SheetPublishError,
type SheetCheckOutcome,
type SheetIssue,
type SheetPublishErrorKind,
type SheetValidator,
} from './anatomical-sheets'
getSheetVersion,
listOfficialCatalog,
type SheetFailureKind,
} from './sheets'
export {
ASSET_FAILURE_KINDS,
ASSET_OWNER_COLUMNS,
+227
View File
@@ -0,0 +1,227 @@
import type { FaunosteoClient } from './client'
import type { Json } from './database.types'
/**
* Access layer for the official anatomical-sheet workflow (V1-2.1, M4/M5):
* typed wrappers over the server RPCs and a closed set of failure kinds. The
* server is the only authority: every RPC answers a closed code (SQLSTATE plus
* a lowercase dotted message), never a value or free text. This module folds
* those answers, the session and the network into one kind the UI phrases
* (`sheet.failure.<kind>`), exactly as `records.ts` does for V1-1. No document
* validation happens here: the Rust core (in the page) and the worker verdict
* decide; the former client publication gate is gone (publication takes a
* review id only).
*
* The screens that call these wrappers arrive in V1-2.5 onward; V1-2.1 ships
* the access layer and its types only.
*/
/** Every closed failure the sheet RPCs raise (contract §6.5, §6.7, §5.2, §5.7). */
export const SHEET_FAILURE_KINDS = [
// session and rights
'authentication_required',
'mfa_required',
'forbidden',
'self_target',
'rights.account',
'rights.capability',
'rights.mfa',
'rights.owner',
'rights.catalog',
'not_found',
// platform roles (AR-1 B)
'role_active',
'role_inactive',
'last_owner',
'target_invalid',
'target_factor_missing',
'operator_path_only',
// catalogue rights
'grant.active',
'grant.ineligible',
'grant.revoked',
'grant.self_review',
'grant.target_invalid',
// drafts and saving
'draft_conflict',
'draft.unchanged',
'draft.frozen',
'draft.not_a_draft',
'document.shape',
'document.species',
'document.too_large',
// sheet and species state
'sheet.inactive',
'sheet.state',
'sheet.no_source',
'sheet.published_history',
'sheet.historical_read_only',
'sheet.species_invalid',
'species.exists',
'species.not_active',
'species.not_inactive',
// review rounds
'round.open',
'round.terminal',
'round.not_open',
'review.digest',
'review.uncoverable',
'review.separation',
'review.groups.uncovered',
'version.not_published',
'version.has_rounds',
// verdict and publication
'verdict.missing',
'verdict.stale',
'verdict.fingerprint',
'publish.review.missing',
'publish.inherited.present',
'publish.species.inactive',
'publish.species.other',
'publish.drawing.missing',
'publish.drawing.changed',
// uploads and working copy
'upload_missing',
'size_mismatch',
'working_copy.source_invalid',
'working_copy.exists',
'working_copy.assets_missing',
// shared
'invalid_input',
'rate_limited',
'session_expired',
'network',
'unavailable',
] as const
export type SheetFailureKind = (typeof SHEET_FAILURE_KINDS)[number]
const KIND_SET: ReadonlySet<string> = new Set(SHEET_FAILURE_KINDS)
export class SheetFailure extends Error {
readonly kind: SheetFailureKind
constructor(kind: SheetFailureKind, cause?: unknown) {
super(`sheet: ${kind}`, { cause })
this.name = 'SheetFailure'
this.kind = kind
}
}
interface PostgrestLikeError {
code?: string | null
message?: string
}
/**
* Folds a PostgREST answer into a closed kind. The RPCs raise the closed code
* as the message (SQLSTATE 42501, P0001, 55000, 23514 or P0002); a message
* outside the closed set, a session error (401 / PGRST30x) and a dropped
* request each map to their own kind. Fails closed on anything unknown.
*/
export function classifySheetError(error: unknown, status?: number): SheetFailureKind {
if (error instanceof SheetFailure) return error.kind
if (error instanceof TypeError) return 'network'
const e = (error ?? {}) as PostgrestLikeError
if (e.message && KIND_SET.has(e.message)) return e.message as SheetFailureKind
if (status === 401 || e.code?.startsWith('PGRST30')) return 'session_expired'
if (status === 0) return 'network'
return 'unavailable'
}
export function failSheet(error: unknown, status?: number): never {
throw new SheetFailure(classifySheetError(error, status), error)
}
// --- Rights (owner, aal2) --------------------------------------------------
export async function grantCatalogRight(
client: FaunosteoClient,
args: {
user_id: string
kind: 'catalog_reader' | 'sheet_editor' | 'sheet_reviewer' | 'sheet_publisher'
reason: string
verification_note?: string
expires_at?: string
},
): Promise<string> {
const { data, error, status } = await client.rpc('grant_catalog_right', args)
if (error) failSheet(error, status)
return data
}
export async function revokeCatalogRight(
client: FaunosteoClient,
grantId: string,
reason: string,
): Promise<string> {
const { data, error, status } = await client.rpc('revoke_catalog_right', {
grant_id: grantId,
reason,
})
if (error) failSheet(error, status)
return data
}
export async function listCatalogGrants(client: FaunosteoClient): Promise<Json> {
const { data, error, status } = await client.rpc('list_catalog_grants')
if (error) failSheet(error, status)
return data
}
// --- Sheets, drafts, review, publication -----------------------------------
export async function createOfficialSheet(
client: FaunosteoClient,
slug: string,
document: Json,
): Promise<string> {
const { data, error, status } = await client.rpc('create_official_sheet', { slug, document })
if (error) failSheet(error, status)
return data
}
export async function saveSheetDraft(
client: FaunosteoClient,
args: { version_id: string; expected_revision: number; document: Json; change_note?: string },
): Promise<Json> {
const { data, error, status } = await client.rpc('save_sheet_draft', args)
if (error) failSheet(error, status)
return data
}
export async function submitSheetReview(
client: FaunosteoClient,
args: { version_id: string; expected_revision: number; note?: string },
): Promise<string> {
const { data, error, status } = await client.rpc('submit_sheet_review', args)
if (error) failSheet(error, status)
return data
}
export async function decideSheetReview(
client: FaunosteoClient,
args: { review_id: string; approve: boolean; note: string },
): Promise<string> {
const { data, error, status } = await client.rpc('decide_sheet_review', args)
if (error) failSheet(error, status)
return data
}
/** Publishes an approved round. The gate is the server's: no client validation. */
export async function publishSheetVersion(
client: FaunosteoClient,
reviewId: string,
): Promise<string> {
const { data, error, status } = await client.rpc('publish_sheet_version', { review_id: reviewId })
if (error) failSheet(error, status)
return data
}
export async function getSheetVersion(client: FaunosteoClient, versionId: string): Promise<Json> {
const { data, error, status } = await client.rpc('get_sheet_version', { version_id: versionId })
if (error) failSheet(error, status)
return data
}
export async function listOfficialCatalog(client: FaunosteoClient): Promise<Json> {
const { data, error, status } = await client.rpc('list_official_catalog')
if (error) failSheet(error, status)
return data
}