Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/associations/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Association registry API and release

`associationPortal.*` is a user-only `backend:admin` API. Any authenticated user can apply; per-record membership is checked server-side on every mutation. Operators need both `admin:access` and `web:content:write`. No global permissions are granted to representatives.

The registry separates association identity, active membership, review requests and the approved public profile. Registration and access approval do not publish content. Content approval atomically changes the published profile. Invitations are single-use, expire after 14 days and store only token hashes in registry state; accepting binds the actual account but requires operator approval. Notes and other applicants' evidence are filtered from scoped responses. Explicit withdrawal revokes invitation tokens.

Migration `0040_association_portal.sql` backfills existing public associations with distinct UUIDs and preserves numeric catalog IDs, profiles and publication. All imported entries start without representatives. JSON state and its mail outbox are updated within PostgreSQL transactions; row locks serialize decisions, revisions detect stale edits, and per-account command keys support retries. Duplicate registrations can be redirected atomically to access requests on an existing association. No destructive record deletion is exposed.

`web.associations.getAllAssociations` retains the existing public response and adds `extraLinks` for repeated platform links (including Twitch). It reads only published registry snapshots, never private working profiles, notes, membership or evidence. Legacy mutation procedures now return `PRECONDITION_FAILED`; callers must use the reviewed registry.

## Deployment

Coordinate the backend and admin PRs: migrate/deploy backend, then deploy admin. The old admin editor cannot write during the interval. The web PR can precede either because it supports responses without `extraLinks`. Use the normal migration procedure and database backup; these changes do not deploy or migrate production automatically. The migration normalises legacy values to the registry contract (only http(s) links and logos, valid emails). Stop all old backend instances before migrating: writes they make to `web_associations` afterwards are not seen by the registry. Representative names and emails come from the IdP directory, cached for one minute with a fallback to the bare subject. Revoking or leaving cancels that account's pending requests. Rolling back just the application requires care: legacy public rows retain the last approved content even after a registry unpublish, so old readers could expose hidden entries. Restore the coordinated version, not an old reader in isolation.

Keep `ESIGN_DASHBOARD_URL` at `https://admin.polinetwork.org` (shared existing dashboard setting), configure the existing mail transport and Azure Blob storage. The existing cron worker drains the durable outbox every minute; failed messages retry with capped backoff and a stable Message-ID. Sent invite URL bodies are scrubbed. Delivery is at least once: a row is leased briefly, sent outside any transaction, closed as undeliverable (text scrubbed) after 20 attempts, and purged 30 days after delivery. Invites are addressed to the supplied email; approval still targets the account that explicitly accepted.

The admin's `docs/associations/README.md` describes the operator and representative workflow. No Auth repository changes are required: existing OIDC personal accounts and operator permissions are reused.

## Verification

Run `bun run check`, `bun run typecheck`, `bun run test`, `bun run build`. Unit/router tests cover scopes, account isolation, registration versus publication, invitation acceptance, revocation, last-responsible handling, duplicate redirection, revisions and idempotency.

For integration, provide a disposable PostgreSQL server with user/password `seed_test` and `SEED_TEST_DB_PORT`, then run `bun run test tests/associations-postgres.test.ts`. The fixture creates and drops only its own random test database and checks backfill, stable IDs, concurrent create/review, persistence, publication and non-destructive unpublish.

`tests/associations-preview.fixture.ts` is a local browser harness, not an application entrypoint: it trusts synthetic test identities and must never be deployed. Real login, email delivery and Blob upload require a staging smoke test with configured external services.
37 changes: 37 additions & 0 deletions drizzle/0040_association_portal.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
CREATE TABLE "web_association_mail" (
"id" uuid PRIMARY KEY NOT NULL,
"mail" jsonb NOT NULL,
"attempts" integer DEFAULT 0 NOT NULL,
"next_attempt" timestamp with time zone DEFAULT now() NOT NULL,
"sent_at" timestamp with time zone
);
--> statement-breakpoint
CREATE TABLE "web_association_registry" (
"id" uuid PRIMARY KEY NOT NULL,
"state" jsonb NOT NULL,
"creation_key" text NOT NULL,
CONSTRAINT "web_association_registry_creation_key_unique" UNIQUE("creation_key")
);

--> statement-breakpoint
-- Existing public records remain published, but no one is automatically made their representative.
INSERT INTO "web_association_registry" (id, state, creation_key)
SELECT rid, jsonb_build_object(
'id', rid, 'legacyId', a.id, 'revision', 0, 'creator', 'system', 'registered', true, 'status', 'active',
'profile', profile, 'published', profile, 'members', '[]'::jsonb, 'requests', '[]'::jsonb,
'events', '[]'::jsonb, 'invitations', '[]'::jsonb, 'notes', '', 'commands', '[]'::jsonb
), 'legacy:' || a.id
FROM web_associations a
CROSS JOIN LATERAL (SELECT gen_random_uuid() AS rid WHERE a.id IS NOT NULL) ids
CROSS JOIN LATERAL (SELECT jsonb_build_object(
-- Legacy values are normalised to what the registry contract accepts: only http(s) links and logos, valid emails.
'name', left(coalesce(nullif(btrim(a.name), ''), 'Association'), 200), 'acronym', '',
'descriptionIt', left(a.description_it, 20000), 'descriptionEn', left(a.description_en, 20000),
'logo', CASE WHEN a.logo ~* '^https?://[^[:space:]]+$' AND length(a.logo) <= 2048 THEN to_jsonb(a.logo) ELSE 'null'::jsonb END,
'email', CASE WHEN a.email ~ '^[^@[:space:]]+@[^@[:space:]]+\.[^@[:space:]]+$' AND length(a.email) <= 320 THEN a.email ELSE '' END,
'links', coalesce((SELECT jsonb_agg(jsonb_build_object('platform', v.k, 'label', v.k, 'url', v.u) ORDER BY v.ord)
FROM (VALUES (1, 'website', a.website), (2, 'facebook', a.facebook), (3, 'instagram', a.instagram),
(4, 'tiktok', a.tiktok), (5, 'x', a.x), (6, 'youtube', a.youtube), (7, 'telegram', a.telegram),
(8, 'linkedin', a.linkedin), (9, 'spotify', a.spotify)) AS v(ord, k, u)
WHERE v.u ~* '^https?://[^[:space:]]+$' AND length(v.u) <= 2048), '[]'::jsonb)
) AS profile) profiles;
Loading
Loading