mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
2bd42e8fc4
# Which Problems Are Solved Since #10666 (v4.1+, backported to v4.x), metadata values set through actions v1 (`api.metadata.push` and `api.v1.user.appendMetadata`) are always JSON-encoded via `json.Marshal`. This made the write path consistent with the JSON-based read path, but removed the ability to store raw (unencoded) metadata values: - A scalar string is now always stored quoted (`"de"` instead of `de`). - The previous byte-array convention (mapping a string to an integer array in the script, handled by `mapBytesToByteArray` introduced in #5526) now stores the literal integer-array text (e.g. `[100,101]`) instead of the raw bytes. Customers migrating from v3.x whose downstream systems base64-decode metadata values from tokens and expect raw bytes have no way to produce them anymore — changing the consuming system is not always possible. Reverting the default is not an option either, as clients that adopted actions v1 on v4.x now rely on the JSON encoding. # How the Problems Are Solved - Adds a new, opt-in function `api.v1.user.appendMetadataRaw(key, value)` to the actions v1 login flows (external / internal authentication post authentication and pre creation), next to the existing `appendMetadata`. - The value is stored as raw bytes without JSON encoding: - a string is stored as its plain UTF-8 bytes (`de`, not `"de"`) - byte arrays (`Uint8Array` or a plain array of integers 0-255, the old convention) are stored as-is, so existing v3 scripts using a string-to-byte-array helper only need to switch the function name - other types (and empty values) throw an error - The existing `appendMetadata` and `api.metadata.push` behavior remains byte-for-byte unchanged. # Additional Changes - Documented `appendMetadataRaw` (and the JSON encoding behavior of `appendMetadata`) in the external and internal authentication actions docs. - Added unit tests for the new function (through a real goja runtime) and a test locking in the existing `appendMetadata` JSON-encoding behavior. # Additional Context - Regression introduced as a side effect of #10666 (which fixed #10470); the raw byte handling was originally introduced in #5526. - Reported by a customer upgrading from v3.4.x to v4.16.x, whose PostAuthentication action maps token payload claims into user metadata. - Requires backport to v4.x. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 <[email protected]>
@zitadel/docs
Documentation for Zitadel, built with Fumadocs and Next.js.
Getting Started
Ensure you have followed the root quick start to set up dependencies.
Local Development
Ensure all dependencies are installed:
pnpm install
Start the development server:
pnpm nx run @zitadel/docs:dev
The site will be available at http://localhost:3000.
Scripts
Key scripts for documentation workflows:
| Script | Description |
|---|---|
dev |
Starts the development server. |
build |
Builds the production application. |
fetch:remote-content |
Fetches remote tags and referenced content. |
generate |
Runs all generation steps (fetch:remote-content, generate:proto-docs, generate:api-reference, generate:index-pages). |
check:links |
Validates content integrity (broken links, missing frontmatter, schema errors). |
check-types |
Validates typescript types. |
test |
Runs all validation steps (check-types, check:links). |
lint |
checks for code style and syntax errors (ESLint). |
clean |
Cleans the build output and generated files. |
Validation
- Code Quality: Run
pnpm nx run @zitadel/docs:lintto check for syntax and style issues in JS/TS/MDX files. - Content Integrity: Run
pnpm nx run @zitadel/docs:check-linksto validate content structure, including:- Broken internal links
- Missing required front-matter (e.g.,
title) - Image references
Troubleshooting
Issue: Nx configuration not found or "nx" command not found
If you see errors like:
NX Cannot find configuration for task @zitadel/zitadel:@zitadel/docs:generate
Pass --verbose to see the stacktrace.
or
pnpm nx run @zitadel/docs:dev
ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL Command "nx" not found
Did you mean "pnpm nx"?
Root cause: Your dependency cache or node_modules is out of sync.
Solution: Run these commands from the repository root in order:
- Clear node_modules:
rm -rf node_modules— removes the installed dependency folder - Clear pnpm cache:
pnpm cache delete— clears pnpm's internal package cache - Reinstall dependencies:
pnpm install— reinstalls all dependencies fresh - Test the setup:
pnpm nx run @zitadel/docs:generate— verifies everything works
This resolves 99% of setup-related issues.
Contributing
Build Process
The docs build process automatically handles the following steps via generate:
- Downloads required protoc plugins.
- Generates gRPC documentation from proto files.
- Generates API documentation from OpenAPI specs.
- Generates index files for directory structures.
Style Guide
- Variables: Use environment variables in code snippets where possible.
- Embedded Content: Use
_filename.mdxfor content embedded in other pages (not indexed individually). - Code Embedding: Use the
fileproperty in code blocks to embed code from the repo. - Voice: Use active voice and sentence case for titles.
Refer to the Google Developer Style Guide for general guidelines.
Adding Content
All documentation content is located in the content directory. Note that the system strictly accepts only .mdx files.
To add a new page:
- Create a
.mdxfile in the appropriate subdirectory ofcontent. - Register the new page in the sidebar settings at
lib/sidebar-data.tsto make it accessible in the navigation.
Pull Requests
Use docs(<scope>): <short summary> for PR titles.
Pass quality checks before submitting:
pnpm nx run @zitadel/docs:build