@astronox/core 0.2.0 → 0.2.2

package/README.md

@@ -1,8 +1,8 @@
 # AstroNox Core
 
-AstroNox Core is the shared Astro foundation used by AstroNox sites. It owns
-reusable components, composition primitives, interaction patterns, display
-contracts, SEO helpers, and the complete default stylesheet.
+AstroNox Core is a reusable foundation for Astro applications. It provides
+components, composition primitives, interaction patterns, display contracts,
+internationalization and SEO infrastructure, and a complete shared stylesheet.
 
 Product data, product routes, branding, integrations, and business rules stay
 in the consuming site.
@@ -33,11 +33,13 @@ import { Stack, SurfaceGroup } from '@astronox/core/composition';
 </Stack>
 ```
 
-Load the shared visual system once from the consuming application's stylesheet:
+Load the shared visual system once from the consuming application's root
+layout:
 
-```css
-@import '@astronox/core/styles.css';
-@import './site-theme.css';
+```astro
+---
+import '@astronox/core/styles.css';
+---
 ```
 
 Use the remaining entry points for layouts, patterns, primitives, display
@@ -50,26 +52,3 @@ and responsive media presentation are available through the `i18n`, `routing`,
 definitions, translations, route names, product metadata, and assets. Generic
 component labels can extend `defaultCoreMessages` through
 `resolveCoreMessages()` while retaining the English fallback.
-
-## Local Development
-
-`astronox-core` is the only source of truth. A consuming project may link this
-package locally while developing a shared change, but committed dependencies
-must always reference a released package version.
-
-The expected workflow is:
-
-1. Keep an exact published version in the consumer manifest and lockfile.
-2. Link the sibling package locally without touching either file with
-   `npm install --no-save --package-lock=false ../astronox-core`.
-3. Implement and validate the generic change through the linked consumer.
-4. Publish a prerelease or stable package version.
-5. Update the exact consumer dependency before deployment.
-
-Do not edit installed package files or copy `src` folders between projects.
-
-## Releases
-
-AstroNox Core follows semantic versioning. Public entry points are compatibility
-boundaries; internal files may change without notice. The initial `0.x` series
-is reserved for stabilizing the API with the first production consumers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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/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,2 @@
+export * from './contracts';
+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,53 @@
+import { getApps, initializeApp } from 'firebase/app';
+import {
+  GoogleAuthProvider,
+  getAuth,
+  onAuthStateChanged,
+  signInWithPopup,
+  signOut,
+  type User,
+} from 'firebase/auth';
+import type { AuthActor } from '../contracts';
+import type { FirebaseClientConfig } from './contracts';
+
+export type FirebaseGoogleAuthClient = {
+  observe(listener: (actor: AuthActor | null) => void): () => void;
+  signIn(): Promise<AuthActor>;
+  signOut(): Promise<void>;
+};
+
+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 = getAuth(app);
+  const provider = new GoogleAuthProvider();
+  provider.setCustomParameters({ prompt: 'select_account' });
+
+  return {
+    observe(listener) {
+      return onAuthStateChanged(auth, (user) => {
+        listener(user ? toAuthActor(user) : null);
+      });
+    },
+    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;
+    },
+  };
+}

package/src/client/index.ts

@@ -1,3 +1,6 @@
 export * from './clipboard';
 export * from './focus';
+export * from './preferences';
 export * from './scroll';
+export * from '../components/content/MarkdownContent/markdownContentRenderer';
+export * from '../patterns/Table/tableClientController';