@ory/argus 0.1.0

package/assets/skills/login-flow/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: ory-login-flow
+description: Build login, registration, account recovery, email verification, and account settings pages using Ory Elements. Use whenever the user asks for a login page, sign-in UI, sign-up form, "forgot password" flow, account settings page, or wants to wire Ory's self-service flows into a frontend. Ory Elements is the default rendering layer; only fall back to custom UI nodes if Elements cannot run in the target environment.
+---
+
+# Build Auth Pages with Ory Elements
+
+You are building login, registration, recovery, verification, and
+settings pages using **[Ory Elements](https://github.com/ory/elements)**
+— a prebuilt UI component library that renders Ory's self-service flows.
+
+**Default rule: every page in this guide is rendered with Ory Elements.**
+Do not hand-roll forms from `flow.ui.nodes` unless the user has
+explicitly opted out after seeing the Ory Elements path. Custom node
+rendering belongs in the fallback section at the end of this skill.
+
+## Why Ory Elements
+
+- One component per flow (`<Login>`, `<Registration>`, `<Recovery>`,
+  `<Verification>`, `<Settings>`) covers the entire self-service surface.
+- Handles CSRF tokens, error messages, multi-step states, social
+  buttons, passkeys, and MFA prompts automatically.
+- New node types and flow capabilities ship with Elements upgrades —
+  no per-app rewrite needed.
+- Works in Next.js (App Router and Pages Router) and any React SPA.
+
+## Before you start
+
+Check the project setup:
+
+1. Identify the framework: Next.js (App Router preferred), React SPA
+   (Vite, CRA, Remix client routes), Vue, or server-rendered. Vue and
+   server-rendered apps drop into the fallback path below.
+2. Verify Ory Elements and the SDK are installed. If not:
+
+   For Next.js:
+
+   ```bash
+   npm install @ory/elements-react @ory/nextjs @ory/client-fetch
+   ```
+
+   For React SPAs:
+
+   ```bash
+   npm install @ory/elements-react @ory/client-fetch
+   ```
+
+3. Verify `ORY_SDK_URL` or `NEXT_PUBLIC_ORY_SDK_URL` is configured in
+   the environment.
+
+If Ory is not set up at all, suggest the user run
+{{REF_AUTH_SETUP}} first.
+
+## Understand Ory self-service flows
+
+Ory uses a **self-service flow** model. Each auth action
+(login, registration, recovery, verification, settings) is a "flow"
+with these stages:
+
+1. **Initialize** — call the Ory API to create a flow (returns a flow
+   object with UI nodes).
+2. **Render** — display the form. **Ory Elements does this for you.**
+3. **Submit** — post the user's input back to Ory. Ory Elements wires
+   the form action; in the SPA flow you call
+   `updateLoginFlow` / `updateRegistrationFlow` / etc.
+4. **Handle result** — redirect on success, show errors on failure.
+   Ory Elements surfaces errors in-form automatically.
+
+## Build the login page
+
+### Login — Next.js App Router (preferred)
+
+Create `app/auth/login/page.tsx`:
+
+```typescript
+import { Login } from "@ory/elements-react/theme"
+import { getLoginFlow, OryPageLayout } from "@ory/nextjs/app"
+
+export default async function LoginPage(props: {
+  searchParams: Promise<{ flow?: string; return_to?: string }>
+}) {
+  const searchParams = await props.searchParams
+  const flow = await getLoginFlow(searchParams)
+
+  if (!flow) {
+    return null
+  }
+
+  return (
+    <OryPageLayout>
+      <Login flow={flow} />
+    </OryPageLayout>
+  )
+}
+```
+
+### Login — React SPA
+
+Use the same `<Login>` component from `@ory/elements-react/theme`.
+Initialize the flow via the SDK and pass it in:
+
+```typescript
+import { useEffect, useState } from "react";
+import { FrontendApi, Configuration, LoginFlow } from "@ory/client-fetch";
+import { Login } from "@ory/elements-react/theme";
+import "@ory/elements-react/theme/styles.css";
+
+const ory = new FrontendApi(
+  new Configuration({
+    basePath: import.meta.env.VITE_ORY_SDK_URL,
+    credentials: "include",
+  })
+);
+
+export function LoginPage() {
+  const [flow, setFlow] = useState<LoginFlow | null>(null);
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const flowId = params.get("flow");
+
+    const load = flowId
+      ? ory.getLoginFlow({ id: flowId })
+      : ory.createBrowserLoginFlow();
+
+    load.then(setFlow).catch(console.error);
+  }, []);
+
+  if (!flow) return <div>Loading…</div>;
+
+  return <Login flow={flow} />;
+}
+```
+
+`<Login>` handles CSRF, error rendering, social buttons, passkeys,
+and submission for you. Do not unwrap `flow.ui.nodes` here.
+
+## Build the registration page
+
+### Registration — Next.js App Router
+
+Create `app/auth/registration/page.tsx`:
+
+```typescript
+import { Registration } from "@ory/elements-react/theme"
+import { getRegistrationFlow, OryPageLayout } from "@ory/nextjs/app"
+
+export default async function RegistrationPage(props: {
+  searchParams: Promise<{ flow?: string; return_to?: string }>
+}) {
+  const searchParams = await props.searchParams
+  const flow = await getRegistrationFlow(searchParams)
+
+  if (!flow) {
+    return null
+  }
+
+  return (
+    <OryPageLayout>
+      <Registration flow={flow} />
+    </OryPageLayout>
+  )
+}
+```
+
+### Registration — React SPA
+
+Mirror the login pattern: initialize with `createBrowserRegistrationFlow`
+(or `getRegistrationFlow` when a `flow` query param is present) and
+render `<Registration flow={flow} />` from `@ory/elements-react/theme`.
+
+## Build the account recovery page
+
+### Recovery — Next.js App Router
+
+Create `app/auth/recovery/page.tsx`:
+
+```typescript
+import { Recovery } from "@ory/elements-react/theme"
+import { getRecoveryFlow, OryPageLayout } from "@ory/nextjs/app"
+
+export default async function RecoveryPage(props: {
+  searchParams: Promise<{ flow?: string }>
+}) {
+  const searchParams = await props.searchParams
+  const flow = await getRecoveryFlow(searchParams)
+
+  if (!flow) {
+    return null
+  }
+
+  return (
+    <OryPageLayout>
+      <Recovery flow={flow} />
+    </OryPageLayout>
+  )
+}
+```
+
+### Recovery — React SPA
+
+Initialize with `createBrowserRecoveryFlow` and render
+`<Recovery flow={flow} />` from `@ory/elements-react/theme`.
+
+## Build the verification page
+
+### Verification — Next.js App Router
+
+Create `app/auth/verification/page.tsx`:
+
+```typescript
+import { Verification } from "@ory/elements-react/theme"
+import { getVerificationFlow, OryPageLayout } from "@ory/nextjs/app"
+
+export default async function VerificationPage(props: {
+  searchParams: Promise<{ flow?: string }>
+}) {
+  const searchParams = await props.searchParams
+  const flow = await getVerificationFlow(searchParams)
+
+  if (!flow) {
+    return null
+  }
+
+  return (
+    <OryPageLayout>
+      <Verification flow={flow} />
+    </OryPageLayout>
+  )
+}
+```
+
+### Verification — React SPA
+
+Initialize with `createBrowserVerificationFlow` and render
+`<Verification flow={flow} />` from `@ory/elements-react/theme`.
+
+## Build the account settings page
+
+### Settings — Next.js App Router
+
+Create `app/auth/settings/page.tsx`:
+
+```typescript
+import { Settings } from "@ory/elements-react/theme"
+import { getSettingsFlow, OryPageLayout } from "@ory/nextjs/app"
+
+export default async function SettingsPage(props: {
+  searchParams: Promise<{ flow?: string }>
+}) {
+  const searchParams = await props.searchParams
+  const flow = await getSettingsFlow(searchParams)
+
+  if (!flow) {
+    return null
+  }
+
+  return (
+    <OryPageLayout>
+      <Settings flow={flow} />
+    </OryPageLayout>
+  )
+}
+```
+
+### Settings — React SPA
+
+Initialize with `createBrowserSettingsFlow` and render
+`<Settings flow={flow} />` from `@ory/elements-react/theme`. The
+component handles password changes, profile traits, MFA enrollment,
+and connected social providers.
+
+## Add session management
+
+Create a utility to check the current session:
+
+```typescript
+import { FrontendApi, Configuration, Session } from "@ory/client-fetch";
+
+const ory = new FrontendApi(
+  new Configuration({
+    basePath: process.env.NEXT_PUBLIC_ORY_SDK_URL,
+    credentials: "include",
+  })
+);
+
+export async function getSession(): Promise<Session | null> {
+  try {
+    return await ory.toSession();
+  } catch {
+    return null;
+  }
+}
+
+export async function logout(): Promise<void> {
+  const { logout_url } = await ory.createBrowserLogoutFlow();
+  window.location.href = logout_url;
+}
+```
+
+## Add route protection
+
+### Next.js Middleware
+
+Create `middleware.ts` at the project root:
+
+```typescript
+import { createOryMiddleware } from "@ory/nextjs/middleware";
+
+export const middleware = createOryMiddleware({
+  protectedPaths: ["/dashboard", "/settings", "/profile"],
+  publicPaths: ["/", "/auth/login", "/auth/registration", "/auth/recovery"],
+});
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+### React SPA
+
+Wrap protected routes in a `ProtectedRoute` component that calls
+`ory.toSession()` and redirects to `/auth/login` on failure.
+
+## Style and customize
+
+Ory Elements supports theming. Wrap auth pages in `<ThemeProvider>`
+from `@ory/elements-react/theme` and pass a custom theme object.
+Customizing the theme keeps the Elements rendering — you do not need
+to drop down to raw nodes to restyle the forms.
+
+```typescript
+import { ThemeProvider } from "@ory/elements-react/theme";
+
+<ThemeProvider theme={{
+  // Custom colors, fonts, spacing, radii, dark mode tokens, …
+}}>
+  <Login flow={flow} />
+</ThemeProvider>
+```
+
+For larger design changes, the Ory Elements primitives package exposes
+the underlying card, button, and input components — use those before
+falling back to custom node rendering.
+
+## Test the flow
+
+1. Start the dev server and Ory tunnel (if developing locally)
+2. Visit `/auth/registration` to create an account — confirm Elements
+   renders all configured methods (password, social, passkey, etc.)
+3. Visit `/auth/login` to sign in
+4. Verify session is established (check protected routes)
+5. Test `/auth/recovery` with a registered email
+6. Test `/auth/settings` for profile changes
+7. Test logout
+
+## Fallback: rendering UI nodes by hand
+
+Use this path **only** when Ory Elements cannot run in the target
+environment (e.g., a Vue app where the React Elements components are
+not viable, a server-rendered template engine with no client bundle,
+or a constrained native shell). Before choosing this path, confirm
+with the user that mounting an Elements island is not an option.
+
+In that case, iterate `flow.ui.nodes` and render each node based on
+`node.type` (`input`, `text`, `img`, `a`, `script`) and
+`node.attributes`. Group nodes by `node.group` (`default`, `password`,
+`oidc`, `webauthn`, `code`, `lookup_secret`, `totp`) so each method
+renders together. Render `flow.ui.messages` and per-node messages for
+errors. Submit using `flow.ui.action` and `flow.ui.method`. This is
+significantly more code than `<Login flow={flow} />` and must track
+Ory flow API changes manually.
+
+## Next steps
+
+- Add social login providers: use {{REF_SOCIAL_LOGIN}}.
+  Elements renders the buttons automatically once providers are
+  configured server-side.
+- Add multi-factor authentication via Ory project settings — the
+  `<Login>` and `<Settings>` components handle the second-factor UI.
+- Customize the identity schema for additional profile fields. Elements
+  reads the schema from the flow and renders new fields automatically.
+- Set up webhooks for registration events.

package/assets/skills/social-login/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: ory-social-login
+description: Configure social login (OAuth2/OIDC) providers — Google, GitHub, Apple, Microsoft, Discord, Slack, GitLab, Facebook — for an Ory-powered app. Use whenever the user wants "Sign in with Google", social sign-in buttons, OIDC providers, or any third-party identity provider on an Ory project. The skill assumes Ory Elements is rendering the auth UI; with Elements, no frontend changes are needed when adding providers.
+---
+
+# Set up Social Login with Ory + Ory Elements
+
+You are configuring social login (OAuth2/OIDC) providers for an
+Ory-powered application. This adds "Sign in with Google",
+"Sign in with GitHub", and similar buttons to the login and
+registration flows.
+
+**Strong recommendation: render the auth UI with [Ory Elements](https://github.com/ory/elements).**
+With Ory Elements, social buttons appear automatically the moment a
+provider is configured on the project — there is no frontend change
+required for any of the providers below. If the app is using custom
+flow rendering, point the user to {{REF_LOGIN_FLOW}} and
+recommend switching to Ory Elements before adding more providers.
+
+## Prerequisites
+
+1. **Ory CLI** — run `ory version`. If not installed:
+   - macOS: `brew install ory/tap/cli`
+   - npm: `npm install -g @ory/cli`
+
+2. **Ory project** — run `ory list projects` to find the project ID.
+   If no project exists, suggest {{REF_AUTH_SETUP}} first.
+
+3. **Auth pages built with Ory Elements** — confirm the project uses
+   `@ory/elements-react` (look for `<Login>` / `<Registration>` from
+   `@ory/elements-react/theme`). If pages are not built yet, suggest
+   {{REF_LOGIN_FLOW}} first. If a custom UI was hand-rolled,
+   recommend migrating to Ory Elements so social buttons render for
+   free.
+
+## Step 1: Choose providers
+
+Ask the user which social login providers they want. Common options:
+
+| Provider | OIDC Type | What you need |
+| ---------- | ----------- | --------------- |
+| Google | OIDC | Google Cloud Console OAuth2 credentials |
+| GitHub | OAuth2 | GitHub OAuth App or GitHub App |
+| Apple | OIDC | Apple Developer account, Service ID |
+| Microsoft | OIDC | Azure AD app registration |
+| Discord | OAuth2 | Discord Developer Portal application |
+| Slack | OIDC | Slack API app |
+| GitLab | OIDC | GitLab application |
+| Facebook | OAuth2 | Meta Developer app |
+
+## Step 2: Create OAuth2 credentials with each provider
+
+Guide the user through creating credentials for each selected provider.
+They will need to set these up in the provider's developer console.
+
+### Google
+
+1. Go to Google Cloud Console > APIs & Services > Credentials
+2. Create an OAuth 2.0 Client ID (Web application type)
+3. Add authorized redirect URI: `https://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/google`
+4. Copy the **Client ID** and **Client Secret**
+
+### GitHub
+
+1. Go to GitHub > Settings > Developer Settings > OAuth Apps > New OAuth App
+2. Set the Authorization callback URL: `https://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/github`
+3. Copy the **Client ID** and **Client Secret**
+
+### Apple
+
+1. Go to Apple Developer > Certificates, Identifiers & Profiles
+2. Create a Service ID, enable "Sign in with Apple"
+3. Configure the return URL: `https://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/apple`
+4. Create a Key for Sign in with Apple, download the `.p8` file
+5. You'll need: **Service ID** (client_id), **Team ID**, **Key ID**,
+   and the **private key**
+
+### Microsoft
+
+1. Go to Azure Portal > Azure Active Directory > App Registrations > New Registration
+2. Set redirect URI: `https://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/microsoft`
+3. Create a client secret under Certificates & Secrets
+4. Copy the **Application (client) ID** and **Client Secret**
+
+### Discord
+
+1. Go to Discord Developer Portal > Applications > New Application
+2. Under OAuth2, add redirect: `https://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/discord`
+3. Copy the **Client ID** and **Client Secret**
+
+## Step 3: Configure providers in Ory
+
+Use the Ory CLI to add each provider. The configuration uses JSON patches.
+
+### Google OIDC
+
+```bash
+ory patch identity-config <project-id> \
+  --add '/selfservice/methods/oidc/config/providers/-={
+    "id": "google",
+    "provider": "google",
+    "client_id": "<GOOGLE_CLIENT_ID>",
+    "client_secret": "<GOOGLE_CLIENT_SECRET>",
+    "mapper_url": "base64://MAPPER_CONTENT",
+    "scope": ["openid", "email", "profile"]
+  }' \
+  --replace '/selfservice/methods/oidc/enabled=true'
+```
+
+### GitHub OIDC
+
+```bash
+ory patch identity-config <project-id> \
+  --add '/selfservice/methods/oidc/config/providers/-={
+    "id": "github",
+    "provider": "github",
+    "client_id": "<GITHUB_CLIENT_ID>",
+    "client_secret": "<GITHUB_CLIENT_SECRET>",
+    "mapper_url": "base64://MAPPER_CONTENT",
+    "scope": ["user:email"]
+  }' \
+  --replace '/selfservice/methods/oidc/enabled=true'
+```
+
+### Apple OIDC
+
+```bash
+ory patch identity-config <project-id> \
+  --add '/selfservice/methods/oidc/config/providers/-={
+    "id": "apple",
+    "provider": "apple",
+    "client_id": "<APPLE_SERVICE_ID>",
+    "apple_team_id": "<TEAM_ID>",
+    "apple_private_key_id": "<KEY_ID>",
+    "apple_private_key": "<PRIVATE_KEY_CONTENTS>",
+    "mapper_url": "base64://MAPPER_CONTENT",
+    "scope": ["openid", "email", "name"]
+  }' \
+  --replace '/selfservice/methods/oidc/enabled=true'
+```
+
+### Microsoft OIDC
+
+```bash
+ory patch identity-config <project-id> \
+  --add '/selfservice/methods/oidc/config/providers/-={
+    "id": "microsoft",
+    "provider": "microsoft",
+    "client_id": "<MICROSOFT_CLIENT_ID>",
+    "client_secret": "<MICROSOFT_CLIENT_SECRET>",
+    "microsoft_tenant": "common",
+    "mapper_url": "base64://MAPPER_CONTENT",
+    "scope": ["openid", "email", "profile"]
+  }' \
+  --replace '/selfservice/methods/oidc/enabled=true'
+```
+
+### Discord OIDC
+
+```bash
+ory patch identity-config <project-id> \
+  --add '/selfservice/methods/oidc/config/providers/-={
+    "id": "discord",
+    "provider": "discord",
+    "client_id": "<DISCORD_CLIENT_ID>",
+    "client_secret": "<DISCORD_CLIENT_SECRET>",
+    "mapper_url": "base64://MAPPER_CONTENT",
+    "scope": ["identify", "email"]
+  }' \
+  --replace '/selfservice/methods/oidc/enabled=true'
+```
+
+## Step 4: Create Jsonnet data mappers
+
+Each provider needs a Jsonnet mapper that maps the provider's claims
+to Ory identity traits. Create a mapper file for each provider.
+
+### Standard email-based mapper
+
+This works for Google, GitHub, Microsoft, Discord, and most providers:
+
+```jsonnet
+local claims = {
+  email_verified: false,
+} + std.extVar('claims');
+
+{
+  identity: {
+    traits: {
+      [if 'email' in claims && claims.email_verified then 'email' else null]: claims.email,
+    },
+  },
+}
+```
+
+### Apple mapper
+
+Apple sends name data only on first login:
+
+```jsonnet
+local claims = {
+  email_verified: false,
+} + std.extVar('claims');
+
+{
+  identity: {
+    traits: {
+      [if 'email' in claims && claims.email_verified then 'email' else null]: claims.email,
+    },
+  },
+}
+```
+
+To use these mappers, either:
+
+1. Base64-encode the Jsonnet and use `mapper_url: "base64://..."`
+   in the provider config
+2. Host the mapper at a URL and use `mapper_url: "https://..."`
+   in the provider config
+
+To base64-encode a mapper file:
+
+```bash
+base64 -i mapper.jsonnet
+```
+
+Then set `mapper_url` to `"base64://<encoded-content>"` in the provider configuration.
+
+## Step 5: Verify social login in the UI (Ory Elements)
+
+If the app uses Ory Elements (the recommended setup), **no frontend
+changes are needed**. The `<Login>` and `<Registration>` components
+read the available methods from the flow object and render the
+appropriate social buttons automatically — including provider icons
+and labels.
+
+Reload the login page and confirm the new buttons appear. If they do
+not:
+
+- Confirm OIDC is enabled and the provider was added (Step 7
+  troubleshooting commands).
+- Confirm the page is rendering `<Login flow={flow} />` from
+  `@ory/elements-react/theme`, not a custom UI.
+- Confirm the flow was re-initialized after the provider was added
+  (a stale flow id from before the change will not include the new
+  buttons).
+
+### Fallback: custom UI rendering of OIDC nodes
+
+Use this only if the user has explicitly chosen not to use Ory
+Elements. In that case, render the OIDC nodes from the flow:
+
+```typescript
+flow.ui.nodes
+  .filter(node => node.group === "oidc")
+  .map(node => {
+    // Each node represents a social login button.
+    // node.attributes contains the provider id and label.
+    // Render a button that submits the form with the provider value.
+  });
+```
+
+Before going down this path, recommend switching to Ory Elements via
+{{REF_LOGIN_FLOW}} so future provider additions don't require
+frontend work.
+
+## Step 6: Test each provider
+
+For each configured provider:
+
+1. Go to the login page
+2. Click the social login button for the provider — Ory Elements
+   should already be rendering it
+3. Complete the OAuth flow with the provider
+4. Verify you're redirected back and a session is created
+5. Check the identity was created: `ory list identities --project <project-id>`
+6. Test the registration flow — a new user signing in via social should auto-register
+7. Test account linking — an existing user should be able to link a social provider
+
+## Step 7: Handle account linking
+
+When a user logs in with a social provider whose email matches an
+existing account, Ory can either:
+
+- **Link automatically** — merge the social identity with the existing account
+- **Require manual linking** — prompt the user to log in with their
+  existing method first
+
+Configure the linking strategy:
+
+```bash
+ory patch identity-config <project-id> \
+  --replace '/selfservice/methods/oidc/config/enabled=true'
+```
+
+When manual linking is required, Ory Elements renders the linking
+prompt automatically — no UI work needed.
+
+## Troubleshooting
+
+- **Redirect URI mismatch**: Ensure the redirect URI in the provider's
+  console exactly matches what Ory expects: `https://<slug>.projects.oryapis.com/self-service/methods/oidc/callback/<provider-id>`
+- **No social buttons showing with Ory Elements**: Verify OIDC is
+  enabled and at least one provider is configured:
+  `ory get identity-config <project-id> --format json | jq '.selfservice.methods.oidc'`
+  Then reload the page so a fresh flow is initialized.
+- **No social buttons showing with a custom UI**: The custom UI must
+  iterate `flow.ui.nodes` filtered by `group === "oidc"`. The simplest
+  fix is to migrate to Ory Elements.
+- **Mapper errors**: Test the Jsonnet mapper locally with sample claims data
+- **Local development**: Use `ory tunnel` to proxy requests — social
+  login requires proper cookie handling that localhost alone can't provide