feat: anonymous public registration sessions

[TrevorBasinger]

Summary

Adds anonymous-public registration-session publishing for roar register --public and roar put --public.

When GLaaS advertises support, roar now uses staged registration sessions for anonymous public publishes instead of the legacy one-shot /api/v1/sessions path. Finalize is server-authoritative: roar stages jobs/artifacts, sends lightweight staged-count expectations, and trusts the hash returned by GLaaS.

Falls back to legacy anonymous session registration when the server does not advertise the required capabilities.

Flow

flowchart TD
    A[roar register --public / roar put --public] --> B[GET /api/v1/health]

    B --> C{Server supports anonymous_public + server-authoritative finalize?}

    C -- No --> L[Legacy anonymous publish]
    L --> L1[POST /api/v1/sessions]
    L1 --> L2[Return session hash/url]

    C -- Yes --> D{Bearer auth present?}
    D -- Yes --> E[Authenticated registration session]
    D -- No --> F{SSH credentials available?}

    F -- No --> H[Anonymous-public registration session]
    F -- Yes --> G[Probe SSH auth]

    G -- SSH accepted --> E
    G -- SSH rejected --> H
    G -- Inconclusive --> E

    E --> E1[POST /api/v1/registration-sessions]
    E1 --> E2[Stage jobs/artifacts with authenticated auth]
    E2 --> E3[Finalize authenticated/scoped session]

    H --> H1[POST /api/v1/registration-sessions mode=anonymous_public]
    H1 --> H2[Receive registration_session_token]
    H2 --> H3[Stage jobs/artifacts with RegistrationSession token]
    H3 --> H4[POST finalize with expected staged counts]
    H4 --> H5[Use server-returned authoritative hash]

Loading

Anonymous-public staged finalize

sequenceDiagram
    participant R as roar
    participant A as GLaaS API
    participant DB as Staged lineage DB

    R->>A: GET /api/v1/health
    A-->>R: anonymous_public=true<br/>finalize_server_authoritative_hash=true

    R->>A: POST /api/v1/registration-sessions<br/>{ mode: "anonymous_public" }
    A-->>R: registration_session_id<br/>registration_session_token

    R->>A: POST /registration-sessions/:id/jobs/batch<br/>Authorization: RegistrationSession token
    A->>DB: Persist staged jobs

    R->>A: POST /registration-sessions/:id/jobs/:uid/inputs|outputs<br/>Authorization: RegistrationSession token
    A->>DB: Persist staged artifact links

    R->>A: POST /registration-sessions/:id/finalize<br/>{ expected: { jobs, inputs, outputs } }
    A->>DB: Read persisted staged lineage
    A->>A: Validate staged counts
    A->>A: Compute canonical hash server-side
    A-->>R: { hash, canonical_version, staged_counts }

Loading

Auth decision model

flowchart LR
    A[Publish request] --> B{Public and unscoped?}

    B -- No --> C[Require authenticated/scoped path]
    B -- Yes --> D{Bearer token?}

    D -- Yes --> E[Attributed authenticated publish]
    D -- No --> F{SSH credentials?}

    F -- No --> G[Anonymous-public publish]
    F -- Yes --> H[Probe SSH against GLaaS]

    H -- Accepted --> I[Attributed SSH publish]
    H -- Rejected --> G
    H -- Inconclusive --> I

Loading

Notable behavior

• Anonymous public publishes use Authorization: RegistrationSession for staged writes/finalize.
• roar no longer predicts/sends expected_hash for anonymous-public finalize.
• roar sends count expectations instead:
  • jobs
  • inputs
  • outputs
• GLaaS remains the canonical hash authority.
• Existing authenticated bearer/SSH registration-session flows are preserved.
• Older servers fall back to legacy anonymous /api/v1/sessions.

Verification

ruff format .
ruff check .
mypy roar

python -m pytest \
  tests/application/publish/test_session.py \
  tests/application/publish/test_put_preparation.py \
  tests/application/publish/test_register_preparation.py \
  tests/application/publish/test_remote_registry.py \
  tests/integrations/glaas/test_client.py \
  tests/integration/test_public_publish_intent_cli.py \
  tests/unit/test_canonical_session_hash.py -q