@astronox/core 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [
@@ -30,10 +30,15 @@
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client/index.ts",
+    "./admin": "./src/admin/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./auth/firebase": "./src/auth/firebase/index.ts",
+    "./auth/firebase/client": "./src/auth/firebase/client.ts",
     "./components": "./src/components/index.ts",
     "./composition": "./src/composition/index.ts",
     "./config": "./src/config/index.ts",
     "./data": "./src/data/index.ts",
+    "./data/firestore/client": "./src/data/firestore/client/index.ts",
     "./display": "./src/display/index.ts",
     "./i18n": "./src/i18n/index.ts",
     "./layouts": "./src/layouts/index.ts",
@@ -62,6 +67,7 @@
     "astro": "^7.0.0"
   },
   "dependencies": {
+    "firebase": "^12.0.0",
     "zod": "4.4.3"
   },
   "devDependencies": {

package/src/admin/cache.ts

@@ -0,0 +1,217 @@
+import type { AdminPage } from './contracts';
+
+export type AdminResourceCacheSerializer<TItem, TStored> = {
+  parse(value: unknown): TItem | null;
+  serialize(item: TItem): TStored;
+};
+
+export type AdminResourceCacheConfig<TItem, TStored> = {
+  collectionKey: string;
+  editorKey: string;
+  getKey(item: TItem): string;
+  serializer: AdminResourceCacheSerializer<TItem, TStored>;
+  sort(items: readonly TItem[]): TItem[];
+  ttlMs?: number;
+};
+
+type StoredPage<TStored> = {
+  expiresAt: number;
+  items: TStored[];
+  nextCursor?: string;
+};
+
+type StoredEditor<TStored> = {
+  actorId: string;
+  expiresAt: number;
+  item: TStored;
+};
+
+const localCursorPrefix = 'cache:';
+
+export function createAdminResourceCache<TItem, TStored>({
+  collectionKey,
+  editorKey,
+  getKey,
+  serializer,
+  sort,
+  ttlMs = 10 * 60 * 1000,
+}: AdminResourceCacheConfig<TItem, TStored>) {
+  const collectionCacheKey = (actorId: string) =>
+    `${collectionKey}:${encodeURIComponent(actorId)}`;
+  const editorCacheKey = (id: string) =>
+    `${editorKey}:${encodeURIComponent(id)}`;
+
+  const readSnapshot = (actorId: string): AdminPage<TItem> | null => {
+    try {
+      const key = collectionCacheKey(actorId);
+      const raw = sessionStorage.getItem(key);
+      if (!raw) return null;
+      const stored = JSON.parse(raw) as Partial<StoredPage<TStored>>;
+      if (
+        typeof stored.expiresAt !== 'number' ||
+        stored.expiresAt <= Date.now() ||
+        !Array.isArray(stored.items)
+      ) {
+        sessionStorage.removeItem(key);
+        return null;
+      }
+
+      const items: TItem[] = [];
+      for (const value of stored.items) {
+        const item = serializer.parse(value);
+        if (!item) {
+          sessionStorage.removeItem(key);
+          return null;
+        }
+        items.push(item);
+      }
+
+      return {
+        items: sort(items),
+        nextCursor:
+          typeof stored.nextCursor === 'string' ? stored.nextCursor : undefined,
+      };
+    } catch {
+      return null;
+    }
+  };
+
+  const write = (actorId: string, page: AdminPage<TItem>): void => {
+    try {
+      const payload: StoredPage<TStored> = {
+        expiresAt: Date.now() + ttlMs,
+        items: sort(page.items).map(serializer.serialize),
+        nextCursor: page.nextCursor,
+      };
+      sessionStorage.setItem(
+        collectionCacheKey(actorId),
+        JSON.stringify(payload),
+      );
+    } catch {
+      // Storage is an optimization and must never block administration.
+    }
+  };
+
+  return {
+    editorKey,
+    isLocalCursor(cursor?: string): boolean {
+      return cursor?.startsWith(localCursorPrefix) === true;
+    },
+    read(
+      actorId: string,
+      input?: { cursor?: string; limit?: number },
+    ): AdminPage<TItem> | null {
+      const cached = readSnapshot(actorId);
+      if (!cached) return null;
+      if (input?.cursor && !input.cursor.startsWith(localCursorPrefix)) {
+        return null;
+      }
+      const offset = input?.cursor
+        ? Number.parseInt(input.cursor.slice(localCursorPrefix.length), 10)
+        : 0;
+      if (!Number.isSafeInteger(offset) || offset < 0) return null;
+      const limit = Math.max(1, Math.floor(input?.limit ?? 25));
+      const end = Math.min(cached.items.length, offset + limit);
+      return {
+        items: cached.items.slice(offset, end),
+        nextCursor:
+          end < cached.items.length
+            ? `${localCursorPrefix}${end}`
+            : cached.nextCursor,
+      };
+    },
+    find(actorId: string, id: string): TItem | null {
+      return (
+        readSnapshot(actorId)?.items.find((item) => getKey(item) === id) ??
+        null
+      );
+    },
+    readEditor(actorId: string, id: string): TItem | null {
+      try {
+        const key = editorCacheKey(id);
+        const raw = sessionStorage.getItem(key);
+        if (!raw) return null;
+        const stored = JSON.parse(raw) as Partial<StoredEditor<TStored>>;
+        if (
+          stored.actorId !== actorId ||
+          typeof stored.expiresAt !== 'number' ||
+          stored.expiresAt <= Date.now()
+        ) {
+          sessionStorage.removeItem(key);
+          return null;
+        }
+        return serializer.parse(stored.item);
+      } catch {
+        return null;
+      }
+    },
+    write,
+    append(actorId: string, page: AdminPage<TItem>): void {
+      const cached = readSnapshot(actorId);
+      if (!cached) return;
+      const items = new Map(cached.items.map((item) => [getKey(item), item]));
+      page.items.forEach((item) => items.set(getKey(item), item));
+      write(actorId, {
+        items: [...items.values()],
+        nextCursor: page.nextCursor,
+      });
+    },
+    upsert(actorId: string, item: TItem): void {
+      const cached = readSnapshot(actorId);
+      if (!cached) return;
+      const items = new Map(
+        cached.items.map((candidate) => [getKey(candidate), candidate]),
+      );
+      items.set(getKey(item), item);
+      write(actorId, {
+        items: [...items.values()],
+        nextCursor: cached.nextCursor,
+      });
+    },
+    remove(actorId: string, id: string): void {
+      const cached = readSnapshot(actorId);
+      if (cached) {
+        write(actorId, {
+          items: cached.items.filter((item) => getKey(item) !== id),
+          nextCursor: cached.nextCursor,
+        });
+      }
+      try {
+        sessionStorage.removeItem(editorCacheKey(id));
+      } catch {
+        // Cleanup is best effort.
+      }
+    },
+    writeEditor(actorId: string, item: TItem): boolean {
+      try {
+        const payload: StoredEditor<TStored> = {
+          actorId,
+          expiresAt: Date.now() + ttlMs,
+          item: serializer.serialize(item),
+        };
+        sessionStorage.setItem(
+          editorCacheKey(getKey(item)),
+          JSON.stringify(payload),
+        );
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    clear(actorId: string): void {
+      try {
+        sessionStorage.removeItem(collectionCacheKey(actorId));
+        for (let index = sessionStorage.length - 1; index >= 0; index -= 1) {
+          const key = sessionStorage.key(index);
+          if (!key?.startsWith(`${editorKey}:`)) continue;
+          const raw = sessionStorage.getItem(key);
+          if (!raw) continue;
+          const stored = JSON.parse(raw) as Partial<StoredEditor<TStored>>;
+          if (stored.actorId === actorId) sessionStorage.removeItem(key);
+        }
+      } catch {
+        // Cleanup is best effort.
+      }
+    },
+  } as const;
+}

package/src/admin/contracts.ts

@@ -0,0 +1,28 @@
+import type { AuthActor, AuthSession } from '../auth';
+
+export type AdminPage<TItem, TCursor = string> = {
+  items: readonly TItem[];
+  nextCursor?: TCursor;
+};
+
+export interface AdminResource<
+  TItem,
+  TCreateInput,
+  TUpdateInput = TCreateInput,
+  TIndexInput = void,
+> {
+  getIndex(input: TIndexInput): Promise<AdminPage<TItem>>;
+  getDetail(input: { id: string }): Promise<TItem | null>;
+  create(input: TCreateInput, actor: AuthActor): Promise<TItem>;
+  update(
+    input: { id: string; value: TUpdateInput },
+    actor: AuthActor,
+  ): Promise<TItem>;
+  delete(input: { id: string }, actor: AuthActor): Promise<void>;
+}
+
+export type AdminAccess<TResources extends Record<string, unknown>> = {
+  actor: AuthActor;
+  resources: TResources;
+  session: AuthSession;
+};

package/src/admin/index.ts

@@ -0,0 +1,3 @@
+export * from './contracts';
+export * from './cache';
+export * from './module';

package/src/admin/module.ts

@@ -0,0 +1,28 @@
+import type { AuthModule } from '../auth';
+import type { AdminAccess } from './contracts';
+
+export function createAdminModule<
+  TCredential,
+  TCapability extends string,
+  TResources extends Record<string, unknown>,
+>({
+  auth,
+  capability,
+  resources,
+}: {
+  auth: AuthModule<TCredential, TCapability>;
+  capability: TCapability;
+  resources: TResources;
+}) {
+  return {
+    async getActor(token?: string | null) {
+      return (await auth.getSession(token))?.actor ?? null;
+    },
+    async requireAccess(
+      token?: string | null,
+    ): Promise<AdminAccess<TResources>> {
+      const session = await auth.requireCapability(token, capability);
+      return { actor: session.actor, resources, session };
+    },
+  };
+}

package/src/auth/contracts.ts

@@ -0,0 +1,53 @@
+export type AuthClaims = Readonly<Record<string, unknown>>;
+
+export type AuthActor = {
+  id: string;
+  claims: AuthClaims;
+  displayName?: string;
+  email?: string;
+  imageUrl?: string;
+};
+
+export type AuthSession = {
+  actor: AuthActor;
+  expiresAt: Date;
+};
+
+export type AuthSessionGrant = AuthSession & {
+  token: string;
+};
+
+export interface IdentityProvider<TCredential = string> {
+  authenticate(credential: TCredential): Promise<AuthActor>;
+}
+
+export interface SessionProvider<TCredential = string> {
+  create(
+    credential: TCredential,
+    actor: AuthActor,
+  ): Promise<AuthSessionGrant>;
+  get(token: string): Promise<AuthSession | null>;
+  revoke(token: string): Promise<void>;
+}
+
+export interface AuthorizationPolicy<TCapability extends string = string> {
+  allows(actor: AuthActor, capability: TCapability): boolean | Promise<boolean>;
+}
+
+export class AuthenticationError extends Error {
+  readonly code = 'AUTHENTICATION_REQUIRED';
+
+  constructor(message = 'Authentication is required') {
+    super(message);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class AuthorizationError extends Error {
+  readonly code = 'AUTHORIZATION_DENIED';
+
+  constructor(message = 'Access is denied') {
+    super(message);
+    this.name = 'AuthorizationError';
+  }
+}

package/src/auth/firebase/client.ts

@@ -0,0 +1,83 @@
+import { getApps, initializeApp, type FirebaseApp } from 'firebase/app';
+import {
+  browserLocalPersistence,
+  browserPopupRedirectResolver,
+  GoogleAuthProvider,
+  getAuth,
+  initializeAuth,
+  onAuthStateChanged,
+  signInWithPopup,
+  signOut,
+  type Auth,
+  type User,
+} from 'firebase/auth';
+import type { AuthActor } from '../contracts';
+import type { FirebaseClientConfig } from './contracts';
+
+export type FirebaseGoogleAuthClient = {
+  observe(
+    listener: (actor: AuthActor | null) => void,
+    onError?: (reason: unknown) => void,
+  ): () => void;
+  signIn(): Promise<AuthActor>;
+  signOut(): Promise<void>;
+};
+
+function initializeBrowserAuth(app: FirebaseApp): Auth {
+  try {
+    return initializeAuth(app, {
+      persistence: browserLocalPersistence,
+      popupRedirectResolver: browserPopupRedirectResolver,
+    });
+  } catch (reason) {
+    if (
+      typeof reason === 'object' &&
+      reason !== null &&
+      'code' in reason &&
+      reason.code === 'auth/already-initialized'
+    ) {
+      return getAuth(app);
+    }
+    throw reason;
+  }
+}
+
+function toAuthActor(user: User): AuthActor {
+  return {
+    id: user.uid,
+    claims: {},
+    displayName: user.displayName ?? undefined,
+    email: user.email ?? undefined,
+    imageUrl: user.photoURL ?? undefined,
+  };
+}
+
+export function createFirebaseGoogleAuthClient(
+  config: FirebaseClientConfig,
+): FirebaseGoogleAuthClient {
+  const app =
+    getApps().find((candidate) => candidate.name === config.projectId) ??
+    initializeApp(config, config.projectId);
+  const auth = initializeBrowserAuth(app);
+  const provider = new GoogleAuthProvider();
+  provider.setCustomParameters({ prompt: 'select_account' });
+
+  return {
+    observe(listener, onError) {
+      return onAuthStateChanged(
+        auth,
+        (user) => {
+          listener(user ? toAuthActor(user) : null);
+        },
+        onError,
+      );
+    },
+    async signIn() {
+      const result = await signInWithPopup(auth, provider);
+      return toAuthActor(result.user);
+    },
+    async signOut() {
+      await signOut(auth);
+    },
+  };
+}

package/src/auth/firebase/contracts.ts

@@ -0,0 +1,8 @@
+export type FirebaseClientConfig = {
+  apiKey: string;
+  appId: string;
+  authDomain: string;
+  messagingSenderId?: string;
+  projectId: string;
+  storageBucket?: string;
+};

package/src/auth/firebase/index.ts

@@ -0,0 +1 @@
+export * from './contracts';

package/src/auth/index.ts

@@ -0,0 +1,2 @@
+export * from './contracts';
+export * from './module';

package/src/auth/module.ts

@@ -0,0 +1,99 @@
+import {
+  AuthenticationError,
+  AuthorizationError,
+  type AuthActor,
+  type AuthSession,
+  type AuthSessionGrant,
+  type AuthorizationPolicy,
+  type IdentityProvider,
+  type SessionProvider,
+} from './contracts';
+
+export type AuthModule<TCredential, TCapability extends string> = {
+  createSession(credential: TCredential): Promise<AuthSessionGrant>;
+  createAuthorizedSession(
+    credential: TCredential,
+    capability: TCapability,
+  ): Promise<AuthSessionGrant>;
+  getSession(token?: string | null): Promise<AuthSession | null>;
+  requireCapability(
+    token: string | null | undefined,
+    capability: TCapability,
+  ): Promise<AuthSession>;
+  revokeSession(token?: string | null): Promise<void>;
+};
+
+export function createAuthModule<TCredential, TCapability extends string>({
+  authorizationPolicy,
+  identityProvider,
+  sessionProvider,
+}: {
+  authorizationPolicy: AuthorizationPolicy<TCapability>;
+  identityProvider: IdentityProvider<TCredential>;
+  sessionProvider: SessionProvider<TCredential>;
+}): AuthModule<TCredential, TCapability> {
+  async function authenticate(credential: TCredential): Promise<AuthActor> {
+    return identityProvider.authenticate(credential);
+  }
+
+  async function authorize(
+    actor: AuthActor,
+    capability: TCapability,
+  ): Promise<void> {
+    if (!(await authorizationPolicy.allows(actor, capability))) {
+      throw new AuthorizationError();
+    }
+  }
+
+  return {
+    async createSession(credential) {
+      const actor = await authenticate(credential);
+      return sessionProvider.create(credential, actor);
+    },
+
+    async createAuthorizedSession(credential, capability) {
+      const actor = await authenticate(credential);
+      await authorize(actor, capability);
+      return sessionProvider.create(credential, actor);
+    },
+
+    async getSession(token) {
+      if (!token) return null;
+
+      try {
+        return await sessionProvider.get(token);
+      } catch {
+        return null;
+      }
+    },
+
+    async requireCapability(token, capability) {
+      if (!token) throw new AuthenticationError();
+
+      const session = await sessionProvider.get(token);
+      if (!session) throw new AuthenticationError();
+      await authorize(session.actor, capability);
+      return session;
+    },
+
+    async revokeSession(token) {
+      if (!token) return;
+      await sessionProvider.revoke(token);
+    },
+  };
+}
+
+export function requireClaim<TCapability extends string>(
+  claim: string,
+  expected: unknown,
+  capability?: TCapability,
+): AuthorizationPolicy<TCapability> {
+  return {
+    allows(actor: AuthActor, requestedCapability: TCapability) {
+      if (capability !== undefined && requestedCapability !== capability) {
+        return false;
+      }
+      return actor.claims[claim] === expected;
+    },
+  };
+}