✦Spectra SDK Docs

Agent doc: Auth JS SDK

Package

@spectra-platform/auth-sdk@0.1.10 was manually published to GitHub Packages at 2026-09-05T11:14:21Z.

Role 70 verified registry latest, clean-cache installation, public imports/types and identical downloaded tarball bytes.

Consuming environments need GitHub Packages registry configuration and read access because the package is private.

Published package.

There is no Actions run for this manual publication; the existing automatic publish permission issue is separate.

Purpose

Auth JS SDK handles app-user Google/Apple login, callback relay, session access token retrieval, service token retrieval, refresh, and logout.

API tree

Auth JS SDK
├─ setup
│  ├─ new SpectraAuthClient(config)
│  ├─ createSpectraAuth(config)
│  ├─ createLocalStorageSessionStore()
│  └─ createMemorySessionStore()
├─ login
│  ├─ signInWithGoogle(options?)
│  ├─ preflightSignIn(options?)
│  ├─ signInWithApple(options?)
│  ├─ relaySpectraAuthCallback()
│  └─ readSpectraAuthCallback()
└─ session
   ├─ getSession()
   ├─ getAccessToken({ service?, forceRefresh? })
   ├─ refresh()
   └─ logout()
└─ error
   ├─ SpectraAuthError
   ├─ isSpectraAuthError(error)
   ├─ retryAfterSeconds
   └─ requestId

Public setup inputs

Provider secret, Apple private key, and Keycloak client secret are not browser/mobile setup inputs. Secret Key exposure requires an explicit consuming-project architecture decision. Project Secret Keys are environment-bound, shown once, and have no expiration date.

publicClientId is a current Auth SDK compatibility field, not a primary user-managed product key.

redirectUri is the consuming app callback URL. It is not the Google/Apple provider redirect URL generated by Spectra.

For local browser QA, localhost and 127.0.0.1 are different origins. Register the full app callback URL.

Deployed Auth 63cf46f automatically uses eligible active Test callback origins for Auth SDK CORS.

Preserve existing static/loopback permissions. Same-origin is required for the new insecure HTTP fallback;

it does not remove existing HTTPS cross-origin callback support.

Agent integration order

1. Install @spectra-platform/auth-sdk@0.1.10.

2. Create one SpectraAuthClient for the current app runtime.

3. Configure only public values: projectId, current package compatibility publicClientId if required, environment, redirectUri, optional baseUrl, optional sessionStore.

4. Implement the callback route and call relaySpectraAuthCallback() there.

5. Start with signInWithGoogle(options?) unless the task explicitly includes Apple credentials.

6. After callback relay, verify getSession() returns the app-user session.

7. Verify getAccessToken() returns a user access token.

8. For consuming-backend login verification, send only await auth.getAccessToken() with no service option to the app backend.

9. Pass the same Auth object to Notification, Chat, and Storage SDK clients.

10. Verify logout() clears local session state.

Backend login verification token

The official consuming-backend verification path is:

const token = await auth.getAccessToken();

The app backend then calls:

GET https://auth.spectra.kr/platform/v1/auth/sessions/current
Authorization: Bearer <token>

Do not pass getAccessToken({ service: "chat" }), getAccessToken({ service: "storage" }), or any other service token

to this endpoint. Auth rejects service tokens with 403 AUTH_SESSION_SCOPE_FORBIDDEN.

The backend must compare project_id, public_client_id, and environment from the response with its own expected

configuration before issuing an app session. The endpoint currently does not return email, email_verified, or

email_source.

Local Google QA checklist

Use this checklist when integrating a consuming app such as modo-camp:

1. Use public baseUrl: "https://auth.spectra.kr" unless the task explicitly asks for producer-local Auth.

2. Set redirectUri to the exact local app callback URL.

- http://127.0.0.1:5174/auth/callback

- http://localhost:5174/auth/callback

3. Do not mix localhost and 127.0.0.1 in the same test run.

4. Confirm the same callback URL is saved as the Auth App/Web Callback in Console.

5. Check the new server deployment, active Test callback registration and actual OPTIONS/SDK responses. Do not infer CORS readiness from SDK publication alone.

6. If Apple key/client secret is not issued, skip Apple and verify Google only.

7. Click signInWithGoogle() and confirm the popup reaches Google account chooser.

8. Complete user credential input only with explicit user involvement.

9. After callback, verify getSession() and getAccessToken().

The 2026-08-02 public-test record includes these SDK origins: https://console.spectra.kr, http://localhost:5173,

http://localhost:5174, http://127.0.0.1:5173, and http://127.0.0.1:5174.

Mobile local HTTP contract

Status on 2026-09-05: SDK 0.1.10 is published and install-verified, source

7a7e521aba34e08d7c23a4c46abe64246e7d0546, tag auth-sdk-v0.1.10. Auth/Console 63cf46f deployment and

JWT self-check passed. Registered HTTPS returned five OPTIONS204 and Google/Apple challenge201;

unregistered LAN returned five OPTIONS404 and actual422 without ACAO; owner requests remained401.

The real LAN callback has only been added as a Console draft: save confirmation is pending and no PUT occurred.

Registered LAN CORS, real provider completion and physical-device E2E remain unverified.

77 unit tests, typecheck/build/pack, clean-cache registry installation and public imports/types passed.

Installed-tarball LAN HTTP Chrome desktop/Pixel 7 emulation passed mock Google/Apple login, gates, popup activation and cancellation.

These results are not actual iPhone or public Auth/provider E2E. Read the release table

for final producer commits and separate verification layers. App adapter/configuration alignment is also required.

Use the mobile local HTTP guide for setup, release status and the complete QA checklist.

Public operations

Consumer example

import {
  SpectraAuthClient,
  createLocalStorageSessionStore,
} from "@spectra-platform/auth-sdk";

const auth = new SpectraAuthClient({
  projectId,
  // Current Auth SDK compatibility field. It is not a primary product key.
  publicClientId,
  environment: "test",
  redirectUri,
  sessionStore: createLocalStorageSessionStore(),
});

await auth.signInWithGoogle();
const token = await auth.getAccessToken();
const chatToken = await auth.getAccessToken({ service: "chat" });

Error handling example

import { isSpectraAuthError } from "@spectra-platform/auth-sdk";

try {
  await auth.signInWithGoogle();
} catch (error) {
  if (isSpectraAuthError(error) && error.code === "RATE_LIMITED") {
    console.warn("Spectra Auth is rate limited", {
      status: error.status,
      retryAfterSeconds: error.retryAfterSeconds,
      requestId: error.requestId,
    });
    return;
  }

  throw error;
}

Do not collapse this to only Try again later. in QA output. The request ID and retry window are the useful escalation

fields.

Callback page

import { relaySpectraAuthCallback } from "@spectra-platform/auth-sdk";

relaySpectraAuthCallback();

Backend verification

Backend services should verify Auth access tokens using JWKS or introspection. App profile/domain data is not owned by Auth.

Prohibited implementation shortcuts

Current caveats

Escalate to Platform CS when