Rendered from specs/F07-auth.md — edit it there, not here.

estimate8 ptsL16–32 hEXTRemote auth: secret storage, header injection, 401/403 handling, plain-http warnings — external-integration edge cases beyond LOC. Advisory only — estimated by the project's AI coding agent (Claude Code) on 2026-07-20 from the implementation (1169 LOC across 5 files); not part of the maturity score. Rubric: S13.

value5.8 valueNicheRICE 0.72NARROW reach 2 (5–20% of users) · impact 4 (removes a manual workflow) · confidence 0.8 (domain-reasoned) Decisive for teams on private schema registries and irrelevant to everyone else — high impact inside a narrow workflow. Advisory only — a judgement about worth, not a measurement, estimated by the project's AI coding agent (Claude Code) on 2026-07-25; not part of the maturity score. RICE divides this score by the S13 effort estimate (8 pts). Rubric: S16.

F07 — Remote Schema Authentication

Overview

The extension can fetch JSON Schema files from private HTTPS endpoints using credentials stored securely in the OS keychain. It supports GitHub OAuth, Bearer tokens, and Basic auth.

User Stories

• As a developer using schemas from a private GitHub repo, I want to authenticate with my existing VS Code GitHub session without copying tokens.
• As an enterprise developer using Artifactory, I want to store a Bearer token once and have the extension use it automatically.
• As a developer, I want VS Code's language server to stop showing a red squiggle for private schemas after I configure auth.

Functional Requirements

Configure Auth Command

• F07-FR-01 The command jsonschema.configureSchemaAuth MUST present a Quick Pick of authentication methods for the URL associated with the active file's schema.
• F07-FR-02 If the active file has no remote $schema URL the command MUST prompt the user for a URL.
• F07-FR-03 If the URL is not a remote URL (i.e. not http:// or https://) the command MUST show an informational message and return.

Authentication Methods

• F07-FR-04 GitHub OAuth — the extension MUST obtain a GitHub OAuth token through VS Code's built-in GitHub authentication provider (no user-visible token).
• F07-FR-05 Bearer token — the user MUST be prompted to enter a token; the token MUST be stored in VS Code's Secret Storage (OS keychain), not in plaintext settings.
• F07-FR-06 Basic auth — the user MUST be prompted for a username and password; both MUST be stored in Secret Storage.

Credential Storage and Retrieval

• F07-FR-07 Credentials MUST be keyed by hostname so one set covers all paths under the same host.
• F07-FR-08 When fetching a remote schema the extension MUST automatically apply the stored credentials for the schema's host.
• F07-FR-09 If a fetch returns 401 or 403 the extension MUST surface an AuthRequiredError with the URL so the caller can offer the Configure Auth flow.
• F07-FR-15 A 404 response from a GitHub host (raw.githubusercontent.com, api.github.com, or any *.github.com/*.githubusercontent.com subdomain) MUST also be surfaced as AuthRequiredError when the request carried no Authorization header — GitHub returns 404, not 401/403, for private-repo content when the caller is unauthenticated, specifically so existence can't be inferred without access. A 404 on a request that did carry an Authorization header MUST remain a plain not-found error (the credential may simply lack access to that path, and re-offering Configure Auth would be misleading). Non-GitHub hosts are unaffected: their 404s always stay not-found, since this ambiguity is a GitHub-specific convention.
• F07-FR-14 When stored credentials are attached to a plain-http:// URL the extension MUST warn the user that the credential is sent unencrypted, at most once per host per session. The request MUST still proceed — the warning informs, it does not block.

Discoverability

• F07-FR-10 A 🔒 / 🔓 status bar item MUST be visible when the active file has a remote $schema. It MUST indicate whether credentials are configured for the schema's host. To stay compact the item's label MUST be icon-only (🔒 when configured, 🔓 otherwise); the schema host MUST be shown in the item's tooltip rather than in its label, so the item does not widen with the host's domain length.
• F07-FR-11 When VS Code cannot load a remote schema a code action (lightbulb) MUST appear on the $schema line offering to configure auth.
• F07-FR-12 When the Validate This File command returns a 401/403, the error notification MUST include a Configure Auth button.

Post-Configuration

• F07-FR-13 After auth is successfully configured the extension SHOULD offer to cache the schema locally (see F08) with a Cache Schema button.

Non-Functional Requirements

• F07-NFR-01 Credentials MUST be stored via vscode.SecretStorage; they MUST NOT be written to settings.json or any other plaintext file.
• F07-NFR-02 Token values MUST NOT appear in log output.

Acceptance Criteria

1. Running Configure Schema Authentication… and selecting GitHub OAuth completes without prompting for a token on machines already signed into GitHub in VS Code.
2. Running the command with no remote schema URL shows an information message.

History

• 2026-07-19 — Added F07-FR-14: warn (once per host per session, non-blocking) when credentials are sent over plain http://.
• 2026-07-22 — Added F07-FR-15: an unauthenticated 404 from a GitHub host is treated as authentication-required, since GitHub returns 404 (not 401/403) for private-repo content without access — previously this silently produced a plain not-found error with no Configure Auth offer.

Requirement traceability

Status of each requirement in specs/traceability.json. Test coverage is auto-discovered from [ID] tags in test titles and is not listed here.

Requirement	Status	Implementation	Note
F07-FR-01	implemented	src/SchemaAuthManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F07-FR-02	manual	src/SchemaAuthManager.ts	VS Code API-bound; verified by manual / E2E testing
F07-FR-03	manual	src/extension.ts	VS Code API-bound; verified by manual / E2E testing
F07-FR-04	implemented	src/SchemaAuthManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F07-FR-05	implemented	src/SchemaAuthManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F07-FR-06	implemented	src/SchemaAuthManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F07-FR-07	implemented	src/SchemaAuthManager.ts	credentials keyed by host cover all paths under it
F07-FR-08	implemented	src/SchemaAuthManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F07-FR-09	implemented	src/SchemaAuthManager.ts	AuthRequiredError unit-tested
F07-FR-10	implemented	src/SchemaAuthStatusBar.ts	icon-only label (host moved to the tooltip so the item stays compact); unit-tested via the vscode mock
F07-FR-11	implemented	src/SchemaAuthCodeActionProvider.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F07-FR-12	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F07-FR-13	manual	src/extension.ts	VS Code API-bound; verified by manual / E2E testing
F07-FR-14	implemented	src/SchemaAuthManager.ts	Warn once per host per session on plain-http credential use; never blocks.
F07-FR-15	implemented	src/SchemaAuthManager.ts	isAuthRequiredStatus() treats an unauthenticated GitHub 404 as auth-required
F07-NFR-01	manual	src/SchemaAuthManager.ts	VS Code API-bound; verified by manual / E2E testing
F07-NFR-02	manual	src/SchemaAuthManager.ts	VS Code API-bound; verified by manual / E2E testing

Documented in

Documentation sections tagged spec:F07 (or one of its requirement ids) — 847 of ~542 expected words (100%). The expectation comes from this spec's evaluated complexity of 13.6 (17 documentable requirements — 15 FR, 2 NFR — weighted by kind and by each definition's length).

• ReachREADME.md · 76 words
• Getting startedREADME.md · 81 words
• Private & Authenticated Schemas/guide/authentication · 445 words
• JSON Schema: Insert $schema Declaration/guide/commands · 135 words
• jsonschema.preview.renderTimeout | Type | Default | Minimum |/guide/configuration · 40 words
• Webview security/guide/security · 70 words

Changes over time

• c0d22692026-07-22fix(auth): treat an unauthenticated GitHub 404 as auth-required
• d01c1142026-07-19feat(F07): warn once per host when credentials are sent over plain http
• 161fd1f2026-07-10feat(status-bar): keep binding and auth status items compact (F04-FR-06, F07-FR-10)
• ac906af2026-06-23docs(specs): add software requirements specification