Repository navigation
feat(api): version negotiation, deprecation headers and a breaking-change gate (spike 663) - #575
Open
ExcelDsigN-tech wants to merge 19 commits into
Open
ExcelDsigN-tech wants to merge 19 commits into
ExcelDsigN-tech wants to merge 19 commits into
Conversation
PhaseFeatureFlag lost phase-146..153, phase-editions and phase-timed-drops, and SecurityCounterName lost ~50 counters used by merged spikes. Restoring them clears 96 of the 120 tsc errors on main. Also registers phase-159, phase-161, phase-162 and phase-163 for spikes 659, 661, 662 and 663.
…chamber modules 0d14b9a ("fixed") re-encoded several files as cp1252-decoded UTF-8 and prepended a BOM plus // @ts-nocheck. User-facing strings in the chamber (e.g. "Transacción", "…") shipped corrupted, and a few glyphs (●, ”) were lost outright. Files with no later commits are restored from 0d14b9a^; files edited since get only their mojibake comments repaired. 60001c5 (PHASE-STELLAR#33 refactor) moved ChamberLogStream, ChamberCatalogThumb, PhaserLiqTokenLink and the chamber chrome classes out of fusion-chamber into components/chamber/* but never committed those files, and left five one-word "placeholder" files behind. The four modules are recreated verbatim from the code it deleted; the unused placeholder imports and files are removed.
- offers accept route: spike 674 collab-split fan-out (3e4b562), with the splits binding hoisted so the response can actually read it - IpfsDisplayImg: `fallback` prop destructure (b89c4f2) - wash-screening: washScreenReasonForEdition (3e4b562) - viewer-signature: viewerSignatureShort (f9a08b6; removed by 7cc03e4 while three components still import it) - sqlite-db: exhibitions, price_suggestions, moderation_queue and quest_arcs tables (b89c4f2). Their absence failed 27 tests.
Real bugs the type errors were hiding: - nft-index subscribe: validateWebhookUrl accepted https://127.0.0.1 and every 172.16/12, 100.64/10 and 0/8 literal (SSRF). Now a proper IPv4 range check. - lib/stellar.ts settle verification read meta v1/v3 only and called ContractEventV0.contractId(), which no longer exists, so every settle check fell through to SETTLE_EVENT_NOT_FOUND. It now reads meta v4 (protocol 23) and v3 and takes the emitter from ContractEvent. Still fails closed on any mismatch. - artist-attestation passed a string where an ScAddress is required and decoded an already-decoded retval, so attestation never read true. Also: winback route called a nonexistent addNotification (now createNotification with a winback_reactivation type), wallet-provider declared `controller` twice, duplicate `ok` keys in ve-lock, and Buffer/Uint8Array typing in the ipfs and avatar routes. wallet-provider and stellar.ts are also restored from the 0d14b9a encoding damage.
- artist-profile-client imported describe/it from node:test, so vitest
found no suite
- world-roles-rbac seeded worldRoles.json while the store reads
world-roles.json (serverDataJsonPath("worldRoles"))
- avatar-provenance hashed a string through the bytes-only sha256Hex;
encoding first gives the same digest
- forge-pipeline imported bun:test; the APIs it uses are identical in vitest
- viewer-authorization: Buffer typing for Keypair.sign
eslint.config.mjs imports eslint-config-next, which was never installed, so npm run lint failed outright. dotenv is imported by scripts that the root test suite loads (scripts/reset-phase.ts).
- ethnum 1.5.2 -> 1.5.3 in both lockfiles: 1.5.2 fails to compile on rustc 1.97 (E0512 transmute), which broke cargo test for both crates - mock-token test called an associated fn as a method outside a contract context; it now goes through the generated MockTokenClient phase-protocol still does not compile: see the baseline notes. Three merged spikes each claimed PhaseError discriminants from 18 upward.
tsc is at 0 errors and vitest is green on this branch, so both can gate PRs now. docs/investigations/main-baseline-2026-10-17.md records what was fixed and what is blocked (phase-protocol discriminant collision).
…lient) lib/stellar-wallet-kit.ts is loaded by the wallet provider on every route and imported randomUUID from node:crypto. The client polyfill has no randomUUID, so hydration threw and nothing interactive rendered. The nonce path is browser-only, so it now uses globalThis.crypto.randomUUID().
… behind phase-163 (spike 663, PHASE-STELLAR#526) - lib/api-contract.ts: typed source of truth for 24 operations, statuses read off each handler - lib/api-versioning.ts: X-API-Version / Accept-Version negotiation, typed 406/410, X-API-Version echo, RFC 9745 Deprecation, RFC 8594 Sunset, Link rel=deprecation/successor-version, OpenAPI 3.1 builder and breaking-change diff - middleware.ts negotiates /api/* when the flag is on; api-observability logs and echoes the negotiated version (closed set) - GET /api/versions serves versions, deprecations, changelog, or the OpenAPI document; 404 when the flag is off - docs/api/openapi.json + changelog.json rendered by npm run api:contract - CI: blocking gate that diffs against the target branch snapshot Tests: lib/__tests__/api-versioning.test.ts (18 cases).
…663) The middleware set `Vary: Accept-Version, X-API-Version` on the same response where gated metadata, IPFS and OG routes set `Vary: Authorization`, so a route's cache key could be replaced and a shared cache could serve one viewer's gated response to another. Vary is now a superset of every token an /api route uses (API_VARY_TOKENS), and a test scans app/api so a new token cannot be missed. - scripts/proof-api-versioning-663.ts (npm run proof:663): read-only checks of negotiation and headers on every listed route - spike doc rewritten against the real issue, with checklist and follow-up - docs/spikes/PR_663.md
proof:663 passed 15/15 with FEATURE_PHASE_163=1; with the flag off, /api/versions is 404 and no version headers or negotiation happen. /api/metadata keeps Authorization in Vary.
SEP-53 wallets sign SHA256("Stellar Signed Message:\n" + message). Signals,
world roles, avatar ownership and gated-preview viewer auth verified the
raw prefixed bytes instead, so every real Freighter signature was rejected
with "Invalid signature: payload not signed by this wallet". The unit
tests passed only because they signed the same raw bytes.
- lib/viewer-signature.ts: sep53SignedBytes + verifySep53Signature, used
by verifySignalSignature, verifyWorldRoleSignature and the avatar route
- lib/viewer-authorization.ts: viewerSignatureBytes is now the SHA-256
digest the wallet's key actually signs
- tests sign like a wallet; the official SEP-53 spec vectors are a
regression test; tests/viewer-authorization.test.ts used an address
unrelated to its seed and could never pass
Resolve lib/feature-flags.ts: keep the restored phase-146..153, editions and timed-drops members alongside upstream phase-158..161. The spike flags move to their own branches.
…api-versioning-deprecation Keep both flag rows in the docs and re-add phase-163 to lib/feature-flags.ts.
|
@ExcelDsigN-tech Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
ExcelDsigN-tech
added a commit
to ExcelDsigN-tech/Phase
that referenced
this pull request
Oct 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Versions the public HTTP surface. Middleware negotiates
X-API-Version/Accept-Versionon/api/*, echoes the version, and answers unknown versions with a typed406and retired ones with410. Deprecated routes get RFC 9745Deprecationand RFC 8594Sunsetheaders. A machine-readable OpenAPI contract and changelog are generated from one source, and a blocking CI step stops unversioned breaking changes. Runtime behavior is behindphase-163(default off).Changes
lib/api-contract.ts: typed contract for 24 operations; statuses read per handler.lib/api-versioning.ts: negotiation,versionResponseHeaders,API_VARY_TOKENS, OpenAPI 3.1 builder,diffContractsandcheckContract.middleware.ts: negotiation for/api/*(preflights excluded). The flag off returns the same response as before.lib/api-observability.ts: logs and echoes the negotiated version (known ids only).GET /api/versions: summary, or the OpenAPI document with?format=openapi.docs/api/openapi.json,docs/api/changelog.jsonvianpm run api:contract -- --write..github/workflows/ci.yml: blocking contract gate against the target branch snapshot.scripts/proof-api-versioning-663.ts(npm run proof:663): read-only live proof.Behavior notes
Varyis a superset of every token an/apiroute sets, includingAuthorization, so gated responses keep their cache key. A test scansapp/apito keep the list complete.errorandstatus.Flag and rollback
FEATURE_PHASE_163/NEXT_PUBLIC_FEATURE_PHASE_163, default off. Rollback: unset and restart. No negotiation or version headers,/api/versionsreturns 404, nothing persisted. The CI gate is source-only and stays on.Tests
lib/__tests__/api-versioning.test.ts(19): negotiation precedence, 406/410, RFC header formats, path-template deprecations, the Vary superset scan, contract coverage, snapshot freshness, diff and gate rules, and middleware flag off/on.tsc --noEmit: 0 errors.vitest run: green with flags off. Locally,npm run proof:663passed all 15 checks againstnext devwith the flag on.Live proof
Production build run: 15/15 checks pass with the flag on. With the flag off,
/api/versionsis 404 and no version headers appear./api/metadata/[id]keepsAuthorizationinVary. Details are in the spike doc under "Lab results". No preview deploy; proofs were run against a local production build andnext dev.Follow-up
OpenAPI generated from zod schemas, a changelog backfilled from git history, dual-version serving, response-shape diffing, and route adoption of
createApiRequestContext. Details are in the spike doc.Depends on
#574 (
chore/fix-main-baseline). Merge that first; until it merges, this diff also shows its commits.feat/docs-api-playground(#525) builds on this branch.Closes #526